Implementation, API & Admin Console

1 · One-pager

Mayday is an iPhone personal-safety app that turns "Hey Siri, Mayday" into a full incident: camera burst + SMS to contacts + outbound call to an AI agent + GPS pings for 10 min. The MVP mocks Twilio entirely — backend records the intent to call/text/SMS so we can build the incident pipeline, the dashboard, and the admin console against real data without paying per-minute.

3 · API primitives (mocked Twilio)

Every endpoint the iPhone app and the admin console consume. Authentication is short-lived JWT signed with HS256, scoped per role (user / admin / agent).

3.1 · Mobile → Relay

POST /v1/incidents                        # create incident, returns {id, started_at}
POST /v1/incidents/:id/events             # batched: gps_ping, sensor, app_state
POST /v1/incidents/:id/media              # multipart upload, 30s clip chunks
GET  /v1/incidents/:id                    # full record incl. contact status
POST /v1/incidents/:id/cancel             # user aborts; requires reason
POST /v1/incidents/:id/contacts/notify    # server-side SMS fan-out (mocked)
POST /v1/incidents/:id/voice/initiate     # server-side call to contact (mocked)
WS   /v1/incidents/:id/stream             # real-time event stream

3.2 · Twilio mock → Relay (webhooks, scripted)

POST /v1/webhooks/twilio/sms/status       # queued · sent · delivered · failed
POST /v1/webhooks/twilio/voice/status     # ringing · answered · completed
POST /v1/webhooks/twilio/voice/recording  # recording_url · duration · transcript
POST /v1/webhooks/twilio/voice/dtmf       # user pressed 1/2/3 in call tree

3.3 · Admin → Relay

GET  /v1/admin/incidents                  # filter by status, user, region
GET  /v1/admin/incidents/:id              # full timeline + media
POST /v1/admin/incidents/:id/intervene    # take over, push 911, dispatch field
GET  /v1/admin/users                      # all registered + last active
GET  /v1/admin/audit                      # operator actions · exportable

3.4 · Response shapes (canonical)

// Incident — server-authoritative
{
  "id":          "inc_01HXY...",
  "user_id":     "usr_8x9k",
  "status":      "active" | "resolved" | "cancelled" | "failed",
  "started_at":  "2026-06-27T17:42:11Z",
  "ended_at":    null,
  "last_ping":   { "lat": 37.4220, "lng": -122.084, "t": "..." },
  "media":       [{ "kind": "video", "url": "r2://...", "duration_s": 30 }],
  "contacts":    [{ "name":"Sarah", "phone":"+1...", "status":"answered", "ts":"..." }],
  "voice":       { "call_sid":"CAxxx", "status":"in_call", "recording":null }
}

// Event — append-only audit row
{
  "id":         "evt_01HXY...",
  "incident_id":"inc_01HXY...",
  "kind":       "trigger" | "gps_ping" | "media_uploaded" | "contact_sms_sent" |
                "contact_call_initiated" | "contact_call_answered" | "voice_dtmf" |
                "user_cancelled" | "admin_cancelled" | "admin_intervened",
  "at":         "2026-06-27T17:42:13Z",
  "data":       { ... kind-specific ... }
}

5 · Animated incident dashboard (per-user)

The user's own incident view — same data the admin sees, but scoped to their incidents only. Mockup below is a static frame of the live view; in production this is a WS-driven React/Next.js page with the same colour grammar.

7 · Data model (Drizzle / Postgres)

Three tables that survive every state of the system. The events table is append-only — that single discipline lets us replay any incident deterministically.

// users — minimal PII; identity managed by Clerk/Auth0 in production
users (
  id          text primary key,
  phone       text unique not null,
  name        text,
  created_at  timestamptz default now(),
  last_seen_at timestamptz,
  contacts    jsonb -- [{name, phone, priority}]
)

// incidents — one row per trigger; mutable status
incidents (
  id          text primary key,
  user_id     text references users(id),
  status      text not null -- active | resolved | cancelled | failed,
  started_at  timestamptz not null,
  ended_at    timestamptz,
  last_ping   jsonb,
  contacts_notified jsonb -- [{phone, status, ts}],
  voice       jsonb -- {call_sid, status, recording_url},
  cancel_reason text
)
create index on incidents (status, started_at desc);
create index on incidents (user_id, started_at desc);

// events — append-only audit; INSERT-only, never UPDATE
events (
  id          bigserial primary key,
  incident_id text references incidents(id),
  kind        text not null,  -- trigger | gps_ping | media_uploaded | contact_sms_sent |
                       contact_call_initiated | contact_call_answered | voice_dtmf |
                       user_cancelled | admin_cancelled | admin_intervened
  at          timestamptz default now(),
  data        jsonb
)
create index on events (incident_id, at);
-- Append-only enforced via revoke update/delete on app role

7.1 · Media storage

Video clips and call recordings go to Cloudflare R2 with server-side encryption (AES-256). URLs are short-lived signed (5 min) so the admin console can render evidence without exposing permanent links. Retention: 90 days for user-initiated, 365 days for incidents involving 911 escalation.

9 · Tech stack

9.1 · Env vars (server refuses to start if missing)

NODE_ENV              production | staging | dev
PORT                  8080
DATABASE_URL          postgres://...
REDIS_URL             redis://...
R2_BUCKET             mayday-evidence
R2_ACCESS_KEY         ...
R2_SECRET_KEY         ...
WS_AUTH_SECRET        # HS256 JWT
TWILIO_ADAPTER        mock | real    # default mock in MVP
TWILIO_ACCOUNT_SID    # required only if TWILIO_ADAPTER=real
TWILIO_AUTH_TOKEN     ...
TWILIO_FROM_NUMBER    +1...
SENTRY_DSN            ...
ADMIN_JWT_SECRET      ...

10 · 14-week sprint plan

12 · Use-case coverage (audit vs. usecases.html)

Every UC in usecases.html mapped to the implementation section that covers it. MVP scope is what ships in the first TestFlight build; deferred are explicit post-MVP per the original UC scoping.

13 · Open decisions & locked items

13.1 · Locked (your call this turn)

13.2 · Cancel posture — design decision

Your point about coercion is sharp and the literature backs it: most safety apps have a "cancel within X seconds" because false positives are catastrophic for trust. But the same UI is a vulnerability under threat. Resolution we agreed on: no user-visible cancel in MVP; admin console is the off-switch.

13.3 · Still pending (non-blocking)

1. Domain + SSL for admin console — ops.mayday.dev on a Cloudflare proxy in front of your box?
2. iOS minimum version — iOS 17+ confirmed (App Intents + negative phrases require 17). Confirm we drop iOS 16 support?
3. Beachhead city — SF / Atlanta / NYC for first 50-user TestFlight?
4. Drill cadence — UC-4 says drill in onboarding only. Should it be monthly push-notification prompt?

14 · Audit trail