who_need_help/docs/product-spec.md

Who Need Help — product specification

Status: MVP specification for OpenAI Build Week, 2026-07-18.

Purpose

Who Need Help connects an adult who needs urgent, practical nearby help with an adult volunteer who can provide it without a mandatory fee.

The first-priority scenario lets a requester ask a nearby person to pick up and deliver medication that has already been legally purchased or reserved. The urgent-help mode also covers non-emergency roadside tasks after people and vehicles are away from active danger. The product does not diagnose, prescribe, recommend, sell, reimburse, or handle controlled substances.

Primary user journey

1. A user creates an account and self-attests that they are at least 18.
2. The user creates an urgent request with a title, instructions, approximate public location, expiry time, and a validated urgent-help category.
3. Nearby helpers see the request on a list and map.
4. One helper accepts it; requester and helper receive a private matched chat.
5. Either party may explicitly start live location sharing for the active match. A browser shares only while its page remains open; Android may continue through a visible foreground-service notification after the app is minimized.
6. The requester gives the helper a one-time handover code after receiving help.
7. Both sides confirm completion and may leave a double-blind review.
8. The requester may send a voluntary thank-you through a helper-provided external link. The platform does not collect or route money.

Request lifecycle

open → matched → in_progress → completed

Terminal alternatives are cancelled and expired. The MVP permits one active helper per request. Every state transition is authorized and recorded.

MVP scope

• Passwordless email magic-link authentication, optional passwords, and optional Google OpenID Connect registration/sign-in.
• English default interface plus Ukrainian and Russian translations.
• Medicine pickup/delivery requests.
• Safe, non-emergency fuel delivery, car-wheel help, bicycle and motorcycle problems, vehicle breakdown help, and support after a secured road incident.
• Hierarchical, data-driven categories with validated structured request fields.
• Request list, filters, details, and a MapLibre map.
• Matching, presence, chat, and consent-driven live location updates.
• Configurable location privacy.
• One-time handover confirmation.
• Double-blind reviews and a reputation summary.
• Category proposals and voting.
• Separate social activities for coffee, cinema, public walks, and hikes.
• Organizer-approved activity membership, capacity-safe joins, private group chat, and exact meeting coordinates limited to approved participants.
• Bidirectional blocks, scoped request/assignment/message reports, and audited report-evidence access.
• Role-protected report, account, abuse-signal, request, role, and category moderation.
• A helper leaderboard based primarily on unique location-supported and handover-verified counterpart counts.
• Configurable PostgreSQL-backed action limits shared by every web replica.
• PWA installation and foreground geolocation.
• Native Android WebView client for the same-origin authenticated map and matched chat, plus a user-started native location foreground service with a persistent Stop notification; reproducible debug APK build.
• Admin-only local Codex moderation batch for category proposals.
• Manual public social links plus optional verified GitHub linking. Manual links never receive a verified badge, and OAuth access tokens are not stored.

Explicitly outside the MVP

• Medical advice, prescriptions, pharmacy integrations, medication sale, and controlled-substance delivery.
• Platform payments, escrow, fees, or compulsory compensation.
• Background PWA or unattended location tracking.
• Multiple simultaneous helpers on one request.
• Production-signed Android release, store publication, and native iOS application.
• OAuth verification of public social-profile badges for providers other than GitHub, and automated social-network identity scoring. Google authentication is a private sign-in identity, not a public verified social-profile badge.
• Automatic punitive abuse enforcement and unapproved production thresholds.
• Claims that identity, safety, or fraud prevention is perfect.

Extensibility

Categories form a moderated tree. The seeded urgent-delivery and roadside-help trees already cover medicine pickup, fuel delivery, wheel help, bicycle punctures and chains, motorcycle chains and tyres, vehicle breakdowns, and secured incident support. Each category adds validated text, select, and boolean fields through its stored schema without changing the request form or core state machine. Moderated proposals can extend the tree further.

User-provided social links are visibly marked unverified. A separately configured GitHub OAuth flow can set verified_at after provider authorization; one provider account cannot be linked to two local accounts. The provider access token is discarded rather than stored.

Google OpenID Connect identities are stored separately from public social links. A verified Google email can create a confirmed local account after the same 18+ safety acknowledgement, or can be connected from a recently reauthenticated account-settings session. Matching email addresses never merge accounts automatically, and Google provider tokens are not persisted.

Privacy settings

Every user chooses one location visibility level:

• hidden
• approximate_public (default)
• exact_for_active_match
• exact_public (explicit per-request opt-in)

Public discovery uses either no marker, an approximate marker, or an explicitly public exact marker. Exact active coordinates are ephemeral and no route history is stored. The current point is deleted when sharing ends, a match becomes terminal, or either participant blocks the other. Derived trust signals may be retained.

The data model reserves a direct-message policy for a future general messaging feature. The current product has no unsolicited inbox: chat exists only for matched urgent-help participants or members of an organizer-approved activity, and a block prevents new discovery, joins, and messages.

Success criteria for the hackathon

• A new user can complete the primary journey locally in two browser sessions.
• The debug Android client can authenticate against the local stack, while the separately installable staging variant can use an explicit public HTTPS origin. Both use the request map, matched chat, and user-started foreground sharing on an emulator.
• The same immutable image runs as both web and worker roles.
• Two web replicas and two worker replicas run concurrently in normal development.
• A request, chat message, and location update reach clients connected to different web replicas.
• The repository contains reproducible Compose and Kubernetes deployment paths.
• The feedback page records the main local Codex session identifier for the Build Week submission.