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 hackathon MVP is deliberately narrow: a requester can ask a nearby person to pick up and deliver medication that has already been legally purchased or reserved. 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 medicine-pickup 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 share foreground location for the active match.
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

• Email magic-link/password authentication.
• English default interface plus Ukrainian and Russian translations.
• Medicine pickup/delivery requests.
• Hierarchical, data-driven categories with validated structured request fields.
• Request list, filters, details, and a MapLibre map.
• Matching, presence, chat, and foreground location updates.
• Configurable location privacy.
• One-time handover confirmation.
• Double-blind reviews and a reputation summary.
• Category proposals and voting.
• 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, matched chat, and foreground geolocation flows; reproducible debug APK build.
• Admin-only local Codex moderation batch for category proposals.

Explicitly outside the MVP

• Medical advice, prescriptions, pharmacy integrations, medication sale, and controlled-substance delivery.
• Platform payments, escrow, fees, or compulsory compensation.
• Background PWA location tracking.
• Multiple simultaneous helpers on one request.
• Public activities such as coffee, cinema, or hiking. These will be a separate future Activity mode, not an urgent-help category.
• Production-signed Android release, store publication, and native iOS application.
• OAuth verification and automated social-network identity checks. The MVP supports manually attached public links and marks them unverified.
• Automatic punitive abuse enforcement and unapproved production thresholds.
• Claims that identity, safety, or fraud prevention is perfect.

Extensibility

Categories form a moderated tree and are not compiled into application code. After the MVP the same request workflow can support fuel delivery, roadside help, bicycle punctures, broken motorcycle chains, and urgent household help. Each category can add validated text, select, and boolean fields through its stored schema without changing the request form code or core state machine.

Social links are user-provided references and are visibly marked unverified. The data model reserves verified_at for a future OAuth flow, but the current MVP does not set it.

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 participants, and a block prevents new 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 and use the request map, matched chat, and 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.