119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# 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.
|