# 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.
