129 lines
6.0 KiB
Markdown
129 lines
6.0 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 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
|
|
|
|
- Email magic-link/password authentication.
|
|
- 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.
|
|
|
|
## 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 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. 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.
|
|
|
|
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 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 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.
|