Margi — Complete Replication Bible

This is the master engineering record for Margi. It captures the real shipped architecture, every subsystem, the exact tech stack and versions, environment + deployment, and a full problem-to-solution engineering log so the entire project can be rebuilt from zero by a human or an AI model. The original aspirational planning brief (PWA vision) is preserved verbatim in Appendix A for history.

Project: Margi — offline-first Golden Hour road-safety prototype
Team: Team NovaDrive · IIT Madras National Road Safety Hackathon 2026 (RoadSoS track, CoERS & RBG Labs / MoRTH)
Repository: github.com/Stormynubee/Margi
Primary client: novadrive-mobile/ — native Expo SDK 54 Android app (com.margi.app, margi://)
Optional cloud: novadrive/ — Next.js 14 Sarthi AI BFF + web relay (Vercel)
Brief site (this page): static HTML built from this file → roadsafetyhackathon-six.vercel.app
Tagline: When signal drops, the path still holds. The network failed — the golden hour didn't.

Table of Contents

• What Margi Really Is
• The Two Safety Lanes
• Repository Topology
• Complete Tech Stack And Versions
• Mobile App Architecture
• Expo Router Screen Map
• Core Library Reference
• START Triage FSM
• Golden Hour Packet GHP
• Facilities SQLite And Trauma Tier Ranking
• Emergency Orchestrator
• Hold SOS Quick SOS And Incident Tracker
• Trauma Response HUD
• Naari Shakti Womens Safety Portal
• Crash And Distress Voice Engines
• Sarthi Assistant Offline And Cloud
• Sarthi BFF Internals
• Supabase Backend
• Web Mirror And Bystander Relay
• Brief Site Build Pipeline
• Environment Variables
• Local Development Setup
• Deployment Mobile APK
• Deployment Sarthi BFF
• Testing Strategy
• Engineering Problem And Solution Log
• Replicate From Scratch Playbook
• Honesty Boundaries And Rejected Scope
• Glossary
• Resources And Links
• Multilingual Support and Searchable Tactile Grid Selector

1. What Margi Really Is

Margi is a client-heavy, offline-first emergency system for Indian highway corridors. All medical and routing decisions run on-device; the network is an optional enhancement (SMS to 108, Supabase auth, Gemini LLM chat).

What Margi is NOT (honesty boundaries — keep these in every pitch):

• Not production emergency medical software — no physician-certified triage, no verified national POI registry, no EMS dispatch guarantee.
• Not a PWA as the primary client — early docs describe a Next.js PWA with sql.js; the shipped app is native Expo. (The PWA vision survives as Appendix A.)
• Not always-on crash detection — accelerometer heuristics + experimental voice; native crash adapter is stubbed unless a custom dev build is used.
• Not auto-dial — SOS opens the SMS composer / dialer intent; the user taps Send / Call (platform policy).

Margi provides decision support only. It is not a medical diagnosis. In an emergency, always call 108/112 when possible.

2. The Two Safety Lanes

Margi ships two parallel emergency experiences that share the offline core.

Lane A — Golden Hour (road accident SOS)

flowchart LR
  SOS[Hold SOS 3s / Quick SOS / header SOS] --> Pick[Incident Tracker]
  Pick --> Act[Activation ~6s splash]
  Act --> Orch[runEmergencyOrchestrator]
  Orch --> ICE[ICE SMS intent]
  Orch --> S108[108 SMS intent]
  Orch --> Maps[Google Maps -> nearest trauma POI lat/lng]
  Orch --> Trauma[Trauma Response HUD]
  Trauma --> Triage[START triage FSM]
  Triage --> Route[Facility ranking]
  Route --> GHP[GHP + QR relay]

Lane B — Naari Shakti (women's safety portal)

Gender-gated (self-reported on device) saffron + navy portal: SMS nearest police station, ICE alert, helpline 181, hold-to-activate (2s) distress HUD with optional recording, 112 national fallback when far from the demo seed.

3. Repository Topology

roadsafetyhackathon/                  # monorepo root (git: Stormynubee/Margi)
├── novadrive-mobile/                 # PRIMARY — Expo SDK 54 Android app (ship this)
│   ├── app/                          # expo-router screens (tabs, emergency, naari, sarthi...)
│   ├── src/                          # lib, components, hooks, context, theme
│   ├── scripts/                      # APK build, sarthi check, seed gen, gradle patches
│   ├── assets/                       # icon/splash docs + models/
│   ├── app.json / app.config.js      # Expo config
│   ├── babel.config.js               # babel-preset-expo + reanimated plugin
│   ├── jest.config.js                # ts-jest, node env, src roots, *.test.ts
│   ├── tsconfig.json                 # extends expo base, @/* -> ./src/*
│   └── package.json                  # version 2.0.0
├── novadrive/                        # Next.js 14 Sarthi BFF + web relay (Vercel)
│   ├── src/app/                      # web pages + api/sarthi/{health,chat}
│   ├── src/lib/sarthi/aiConfig.ts    # Gemini provider + probe
│   ├── vercel.json                   # separate Vercel project
│   └── package.json
├── docs/                             # judge docs, specs, brief site source
│   ├── CANON.md                      # single source of truth for scope
│   ├── ARCHITECTURE.md               # technical architecture
│   ├── PHASE3_SETUP.md               # Supabase + Sarthi BFF deploy guide
│   ├── MARGI_MASTER_BRIEF.md         # THIS FILE -> builds the brief site
│   └── site/                         # build-docs.js -> index.html (deployed)
├── supabase/migrations/              # profiles, volunteer_providers, dispatch_events + RLS
├── data/corridors/                   # NH-48 POI verification CSV/JSON inputs
├── scripts/                          # Python Overpass ingest + pytest (build-time only)
├── .github/workflows/                # ci.yml, android-apk.yml, poi-ingest.yml
├── vercel.json                       # ROOT project -> static brief site (docs/site)
├── README.md / JUDGE_START_HERE.md / CHANGELOG.md / CONTRIBUTING.md / SECURITY.md

Critical deployment split (the single biggest gotcha):

The brief-site hosts (roadsafetyhackathon-six.vercel.app, margi-tau.vercel.app) return 404 for /api/sarthi/health. Sarthi must point at the separate novadrive project (e.g. novadrive-eta.vercel.app).

4. Complete Tech Stack And Versions

Mobile (novadrive-mobile/package.json, version 2.0.0)

Cloud BFF (novadrive/package.json, version 0.1.0)

Build-time data pipeline (scripts/)

Python 3 + Overpass API → emergency_seed.db; validated by pytest in CI (poi-ingest.yml). Not bundled into the app at runtime — the mobile app uses an inline seed.

5. Mobile App Architecture

novadrive-mobile is a client-heavy app: the offline core never requires a server.

flowchart TB
  subgraph mobile [novadrive-mobile]
    Plan[Trip + OSRM when online]
    J[Journey HUD + HoldSOS]
    Orch[emergencyOrchestrator]
    S[START Triage FSM]
    DB[(SQLite trauma POI)]
    G[GHP + QR + SMS 108]
    N[Naari Shakti engine]
    Sarthi[Sarthi KB + optional BFF]
    Plan --> J
    J --> Orch
    J --> S
    Orch --> DB
    S --> DB
    DB --> G
    N -.->|parallel| G
    Sarthi -.-> J
  end
  subgraph cloud [optional online]
    SB[(Supabase)]
    BFF[Sarthi BFF on Vercel]
  end
  mobile -.-> SB
  mobile -.-> BFF

Conventions

• Path alias: @/ → ./src/ (tsconfig + babel).
• State: React Context providers wrap the app in app/_layout.tsx: AppProvider (journey, triage FSM, GHP, crash, facilities), SarthiProvider, NaariShaktiProvider, plus QuickMenuProvider in (tabs)/_layout.tsx.
• Data boundaries: auth tokens + relay GHP in SecureStore; profile + accessibility in AsyncStorage; POI in the SQLite file seeded on first launch.
• TDD discipline: every src/lib module that holds logic ships with a colocated .test.ts.

app/
  _layout.tsx              # Root: fonts, providers, Stack
  index.tsx / splash.tsx   # Boot + splash
  home.tsx                 # Standalone home (also see (tabs)/explore)
  auth.tsx                 # Supabase sign-in (Guest mode bypasses)
  settings.tsx             # notifyEmergencyContacts toggle, voice sensitivity
  accessibility.tsx medical.tsx emergency-contacts.tsx
  sarthi.tsx               # full-screen Sarthi chat
  scan.tsx                 # bystander QR scanner
  naari-shakti.tsx         # women's portal
  journey.tsx
  (tabs)/
    _layout.tsx            # MargiTabBar + SarthiOverlayBridge + QuickMenuProvider
    explore.tsx            # Home tab (Drive mode, Quick SOS, Naari, brief, Sarthi FAB)
    drive.tsx              # Journey HUD — Hold SOS lives here
    history.tsx            # Community hazards (~5 km), leaderboard
    profile.tsx            # Medical ICE, voice toggle, a11y
  emergency/
    selection.tsx          # incident type picker + cancel-SOS countdown
    activation.tsx         # 6s activation splash + runEmergencyOrchestrator
    locate.tsx             # GPS capture + reverse geocode
    triage.tsx             # START triage FSM UI
    route.tsx              # facility ranking list + Maps navigate
    response.tsx           # trauma HUD: timer, torch, ICE, QR, first aid
    packet.tsx             # GHP QR + relay URL
    relay.tsx              # bystander relay steps + RahVeer claim
  journey/ depart.tsx complete.tsx feedback.tsx
  settings/ journey-history.tsx
  trip/ _layout.tsx plan.tsx discover.tsx
  brief/ [slug].tsx
  rahveer/ index.tsx claim.tsx
  ngo/ index.tsx register.tsx

export type TriageState =
  | 'AMBULATORY' | 'BREATHING_CHECK' | 'AIRWAY_REPOSITION'
  | 'RESPIRATORY_RATE' | 'PERFUSION_CHECK' | 'MENTAL_STATUS' | 'TAGGED';

export interface TriageContext {
  count: number;
  canWalk: boolean;
  breathing: boolean;
  respiratoryRateOver30: boolean;
  capillaryRefillOk: boolean;
  followsCommands: boolean;
  severeBleeding: boolean;
  triageResult: 'RED' | 'YELLOW' | 'GREEN' | 'BLACK';
  stateLog: string[];
}

export interface GoldenHourPacket {
  id: string;                    // UUID-ish
  createdAt: string;             // ISO8601
  triage: 'RED' | 'YELLOW' | 'GREEN' | 'BLACK';
  location: { lat: number; lng: number; landmark?: string; nhCode?: string; nhKm?: number };
  victims: {
    count: number; canWalk: boolean; breathing: boolean;
    severeBleeding: boolean; capillaryRefillOk: boolean; followsCommands: boolean;
  };
  routing: { facilityName: string; facilityType: 'trauma' | 'hospital' | 'clinic';
             phone: string; etaMinutes: number; distanceKm: number };
  emergency: { dial: string; state: string; language: 'en' | 'hi' | 'ta' };
  relayChain: Array<{ at: string; deviceHint: string }>;
  integrity: string;             // SHA-256 hex digest (corruption check, not crypto signing)
}

ROAD EMERGENCY - Margi
Triage: RED | Victims: 1
Location: NH48 km 87 (13.082700, 80.270700)
Injuries: Not walking, breathing, severe bleeding suspected
TAKE TO: Apollo Trauma Center (12 min / 8.4 km)
Call: 108 (Tamil Nadu)
Generated offline via bystander relay.

CREATE TABLE emergency_nodes (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  lat REAL NOT NULL,
  lng REAL NOT NULL,
  type TEXT NOT NULL,            -- hospital | clinic | police | ambulance
  trauma_tier INTEGER NOT NULL,  -- 1 trauma center, 2 hospital ER, 3 clinic
  emergency_phone TEXT,
  nh_corridor TEXT,
  state TEXT,
  verified INTEGER DEFAULT 0,
  verified_at TEXT
);
CREATE INDEX idx_coords ON emergency_nodes(lat, lng);
CREATE INDEX idx_tier ON emergency_nodes(trauma_tier);

flowchart LR
  start[Activation done] --> coords[Resolve GPS coords]
  coords --> rank[rankFacilities -> nearest trauma POI]
  rank --> plan[planEmergencyOrchestrator]
  plan --> ice{notifyEmergencyContacts?}
  ice -->|yes & ICE set| iceSms[Open ICE SMS intent]
  ice -->|no| skip[skip ICE]
  iceSms --> s108[Open 108 SMS intent]
  skip --> s108
  s108 --> maps[Open Google Maps to facility lat/lng]
  maps --> trauma[Navigate to Trauma Response HUD]

Distress voice (voice/)

Optional YAMNet-based distress classifier, off by default (sensitivity setting in Profile). Even when triggered, the countdown does not auto-open the 108 SMS — fail-safe against false positives. Evaluation: docs/VOICE_CLASSIFIER_EVAL.md.

16. Sarthi Assistant Offline And Cloud

Sarthi is the in-app AI helper. It is offline-first: a deterministic knowledge base answers without any network, and the cloud Gemini BFF is an enhancement.

Decision flow (src/lib/sarthiEngine.ts)

flowchart TD
  msg[User message] --> kb{KB match?}
  kb -->|yes, offline-first| offline[Knowledge base reply]
  kb -->|no| online{Online AND BFF healthy?}
  online -->|yes| cloud[POST /api/sarthi/chat -> Gemini]
  online -->|no| offlineFb[Offline reply + cloud-unavailable prefix]
  cloud -->|error| offlineFb

• matchKnowledgeBase() over SARTHI_KB_ENTRIES (crash, fire, trapped, bleeding, not-breathing, SOS, corridor, medical, greeting, help_general, guest_identity...) in en/hi/ta.
• shouldUseOfflineFirst() keeps emergency/help intents fully offline even when online.
• When the cloud call fails, wrapCloudUnavailableReply() prefixes the offline answer with "Cloud Sarthi (Gemini) is temporarily unavailable. On-device guidance:" so it never silently degrades to a generic boilerplate.
• Health gate: checkSarthiBffHealth() requires ok === true and geminiReachable !== false. The status chip ("Gemini online" vs "Offline KB") is driven by this real probe, not by "is an API key present".

17. Sarthi BFF Internals

novadrive/ is a Next.js 14 app. Only two API routes matter.

src/lib/sarthi/aiConfig.ts

• Reads GOOGLE_GENERATIVE_AI_API_KEY and sanitizes a UTF-8 BOM (\uFEFF) and whitespace that CLI env uploads can prepend (sanitizeGoogleApiKey).
• Scrubs process.env on load so libraries reading the raw var get a clean key.
• Builds the provider explicitly: createGoogleGenerativeAI({ apiKey }) rather than relying on implicit env reads.
• Model: process.env.SARTHI_GEMINI_MODEL || 'gemini-2.5-flash'.
• probeSarthiGemini() performs a real generation (system: 'You are Sarthi health check. Reply in one short word.', prompt: 'ping', maxOutputTokens: 64) and returns { ok, error? } based on whether non-empty text comes back.
• resolveSarthiModel() prefers direct Google when a key exists, else falls back to the AI Gateway string model.

GET /api/sarthi/health (src/app/api/sarthi/health/route.ts)

Returns { ok, service, model, geminiConfigured, geminiReachable, provider, probeError? }, status 200 only when configured and the probe actually reaches Gemini. CORS enabled.

POST /api/sarthi/chat (src/app/api/sarthi/chat/route.ts)

• 503 if not configured.
• Builds a system prompt from the context (journey phase, language en/hi/ta, display name, guest vs auth, medical summary, ICE presence, regional protocols) and calls generateText({ model: resolveSarthiModel(), system, messages, maxOutputTokens: 256 }).
• Returns { reply, actionCard? } (action card appears when corridor/route is mentioned). CORS enabled.

18. Supabase Backend

Project Projectmargi (yllcmksndrhlektbjvcu). Migrations under supabase/migrations/.

Mobile integration:

• src/lib/supabase/client.ts — createClient with expo-secure-store auth persistence; reads EXPO_PUBLIC_SUPABASE_URL + EXPO_PUBLIC_SUPABASE_ANON_KEY (use the publishable sb_publishable_... key, never the secret).
• profileSync.ts — from('profiles') select/upsert; authSession.ts — session helpers.
• ngo/volunteerProviders.ts — from('volunteer_providers'); set verified = true for a demo NGO row.
• emergency/dispatchOrchestrator.ts — from('dispatch_events').insert(...) audit.
• Guest mode bypasses auth entirely so judges never need to sign in.

19. Web Mirror And Bystander Relay

novadrive/src/app/ mirrors the emergency flow for laptop demos and, crucially, hosts the bystander relay:

• /relay (relay/page.tsx) — decodes a ?p= query (ND1: + lz-string), shows triage + location, and offers Google Maps + SMS-to-108 links. This is the URL embedded in the mobile GHP QR.
• */emergency/ — a full web wizard (locate → triage → route → packet → relay) backed by lib/session-store.ts, reusing web copies of startTriageFSM.ts, ghp.ts, and facilities.ts.

Anchor rule: a heading ## N. Title becomes id n-title (lowercased, punctuation stripped, spaces → hyphens). Keep headings ASCII and punctuation-free so the TOC links resolve.

# Mobile (primary)
cd novadrive-mobile
npm install --legacy-peer-deps
npx expo install react-native-worklets babel-preset-expo
cp .env.example .env            # add Sarthi BFF + Supabase keys (optional)
npm test                        # Jest unit tests
npm run typecheck               # tsc --noEmit
npm run android                 # dev build + Metro (Android Studio JBR on Windows)
# or Expo Go on same Wi-Fi:
npm run start:lan

# Cloud BFF
cd ../novadrive
npm install
npm run dev                     # http://localhost:3000
npm run dev:lan                 # -H 0.0.0.0 -p 3000 for device testing

# Brief site
node docs/site/build-docs.js    # regenerate docs/site/index.html

Recommended SOS demo: Guest → Trip → Start Driving → calibration → hold SOS 3s → pick incident → activation → trauma response (verify ICE FAB, timer, torch, Maps opens toward the hospital, not the user pin).

Deploy novadrive/ as a separate Vercel project.

• Import Stormynubee/Margi at vercel.com/new.
• Root Directory → novadrive (not repo root).
• Framework: Next.js (auto).
• Build & Output Settings: Install npm install, Build npm run build, Output Directory empty (delete any docs/site value — that belongs to the brief-site project).
• Env var GOOGLE_GENERATIVE_AI_API_KEY (Production + Preview).
• Deploy; note the URL.

From CLI

cd novadrive
npm install
npx vercel --prod
# add GOOGLE_GENERATIVE_AI_API_KEY in the dashboard, then redeploy

curl https://YOUR-BFF.vercel.app/api/sarthi/health
# expect: { "ok": true, "geminiConfigured": true, "geminiReachable": true, "model": "gemini-2.5-flash" }
node novadrive-mobile/scripts/check-sarthi-bff.cjs https://YOUR-BFF.vercel.app

• Mobile: Jest + ts-jest, testEnvironment: node, roots in src/, pattern /.test.ts (logic only — no .tsx rendering tests). 73 test files / 225 cases. Notable clusters: startTriageFSM, ghp, facilitiesDb, emergencyOrchestrator, sarthiEngine, sarthiKnowledgeBase, voice/distress, naariShakti, home/safety brief.
• Discipline: TDD for every src/lib logic module; keep side effects (intents, navigation, SQLite) behind pure plan functions so they are testable.
• Docs/branding gates: npm run verify:docs, npm run verify:branding.
• CI (ci.yml): Job 1 mobile typecheck + test + verify gates; Job 2 novadrive next build; Job 3 build the brief site.
• POI CI (poi-ingest.yml): Python pytest on scripts/tests for any scripts/ or data/ change.
• Manual: novadrive-mobile/docs/DEVICE_SMOKE_MATRIX.md (device matrix), optional Maestro flows.

• Fixes:

26.5 Fake "GEMINI BFF ONLINE" chip

• Symptom: chip showed online even when Gemini never responded.
• Root cause: status was derived from "is a key configured", not from reachability.
• Fix: status copy (sarthiStatusCopy.ts, app/sarthi.tsx) is driven by the real geminiReachable probe; chip reads "Gemini online" only when the probe truly succeeds, otherwise "Offline KB".

26.6 UTF-8 BOM in the Vercel env key (character at index 0 has value 65279)

• Symptom: health/chat errored with ... character at index 0 has a value of 65279 ....
• Root cause: piping the key via PowerShell into vercel env add prepended a UTF-8 BOM (\uFEFF); @ai-sdk/google sent it verbatim in the auth header.
• Fix: sanitizeGoogleApiKey() strips BOM + whitespace, process.env is scrubbed on load, and the provider is built explicitly with createGoogleGenerativeAI({ apiKey: clean }). Re-added the env without BOM and redeployed.

26.7 Gemini quota exceeded on gemini-2.0-flash

• Symptom: You exceeded your current quota ... free_tier ... limit: 0, model: gemini-2.0-flash.
• Root cause: the key had no free-tier quota for gemini-2.0-flash.
• Fix: switched the default model to gemini-2.5-flash (overridable via SARTHI_GEMINI_MODEL), which had availability for the key. Chat then returned real, contextual replies.

26.8 Health probe false-negative ("Empty model response" / "Unexpected probe reply: i")

• Symptom: chat worked but health reported geminiReachable: false.
• Root cause: the probe demanded the model echo an exact word with a tiny token budget; gemini-2.5-flash returned empty/partial text for the over-constrained prompt.
• Fix: relaxed the probe to a short system + prompt: 'ping' with maxOutputTokens: 64, accepting any non-empty reply as healthy. Health then matched chat reality.

26.9 Maps opened to the user's pin instead of the hospital

• Symptom: orchestrator's Maps step navigated to the victim location, not the destination hospital.
• Root cause: the navigate target used current coords.
• Fix: hospitalNavTarget.ts resolves the ranked facility lat/lng (added lat/lng to the Facility type) and Maps opens toward it.

26.10 Premature SMS before incident selection / false alerts

• Symptom: SMS could fire before the user chose an incident type; voice/crash countdowns risked auto-SMS.
• Fix: unified all SOS entries through the Incident Tracker first; added holdSosReleaseGrace so a quick release doesn't skip the picker; disabled voice detection by default; removed the countdown-0 auto-SMS so the user always confirms.

26.11 Documentation drift (PWA vision vs shipped native app)

• Symptom: docs described a Next.js PWA + sql.js that was never the shipped client.
• Fix: created docs/CANON.md as the single source of truth; marked the old brief as historical (now Appendix A here); README + this bible describe the real Expo app.

26.12 Windows parallel Gradle and C++ compiler OOM crash

• Symptom: Android CLI build (npx expo run:android) crash with CreateProcess error=1455, The paging file is too small for this operation to complete or Gradle Daemon compiler exhaustion.
• Root cause: Default parallel execution inside gradle.properties (org.gradle.parallel=true) coupled with unconstrained C++ compilation threads (e.g. building Reanimated or custom modules) overcommited host system memory on Windows machines.
• Fix: Disabled parallel builds and workers in gradle.properties (org.gradle.parallel=false, org.gradle.workers.max=1) and restricted concurrent C++ compiler processes by launching the build with CMAKE_BUILD_PARALLEL_LEVEL=1 set. This bounds paging size requirements perfectly, enabling stable builds under 1.5GB total JVM memory footprint.

26.13 Prominent 15-language selector reactive translation sync

• Symptom: When translating the core login screen, text fragments did not reactively update when regional (Hindi/Tamil) chips were selected; selector UI felt generic.
• Fix: Designed a robust full-width Expandable Tactile Grid Language Selector containing 15 global locales (with individual flag glyphs, native, and English labels). Built the translation registry (src/lib/translations/ - mapping English, Hindi, Tamil, Spanish, German, Mandarin, etc.) into the reactive state context (useApp()). Selecting a chip reactively re-evaluates all active text keys (getAuthString()) instantly while triggering pleasant haptics (Haptics.notificationAsync).

27. Replicate From Scratch Playbook

To rebuild Margi from zero:

• Monorepo: create novadrive-mobile/ (Expo), novadrive/ (Next.js), docs/, supabase/migrations/, scripts/, .github/workflows/. Add the two vercel.json files (root → brief site; novadrive/ → Next.js).
• Mobile scaffold: npx create-expo-app (SDK 54), add expo-router, the dependency set in §4, the @/ alias, and react-native-reanimated/plugin in babel. Configure app.json (com.margi.app, margi://, camera/location/SMS permissions, plugins).
• Offline core first (TDD): build startTriageFSM.ts (§8) → facilitiesDb.ts + seed (§10) → ghp.ts encoder + integrity (§9), each with .test.ts. This is the demo-critical path; it must work in airplane mode.
• SOS path: HoldSOSButton → Incident Tracker (emergency/selection) → activation (navigate-then-orchestrate, router guard) → emergencyOrchestratorPlan/emergencyOrchestrator (ICE SMS → 108 SMS → Maps to facility) → trauma HUD (response.tsx + TraumaResponseActionBar + useTorch/TorchCameraLayer) → packet (QR) → relay.
• Sarthi: offline KB (sarthiKnowledgeBase.ts) + engine (sarthiEngine.ts) offline-first; health gate (sarthiHealth.ts) requiring geminiReachable. Then the BFF (§17): aiConfig.ts (BOM-safe key, explicit provider, gemini-2.5-flash), /api/sarthi/health (real probe), /api/sarthi/chat.
• Naari Shakti (§14), crash + voice off-by-default (§15).
• Supabase (§18): apply migrations, wire client with SecureStore, keep Guest mode.
• CI/CD (§23–§25): ci.yml, android-apk.yml, poi-ingest.yml.
• Brief site (§20): write this file; node docs/site/build-docs.js; deploy root project.
• Wire env (§21) and verify health endpoints before claiming "online".

28. Honesty Boundaries And Rejected Scope

Deliberately rejected (do not reintroduce without a team vote)

Strategic lesson: judges score reliable offline triage with valid POI data — not machines chirping at each other. Margi's differentiator is information surviving dead zones (GHP + human QR relay).

29. Glossary

30. Resources And Links

In-repo: docs/CANON.md (scope truth), docs/ARCHITECTURE.md, docs/PHASE3_SETUP.md, JUDGE_START_HERE.md, docs/SUBMISSION.md, novadrive-mobile/README.md, novadrive-mobile/docs/DEVICE_SMOKE_MATRIX.md.

31. Multilingual Support and Searchable Tactile Grid Selector

To ensure extreme accessibility across diverse Indian highway demographics and global locales, Margi features a robust, fully localized 15-Language Engine. This system empowers users and first responders to switch the interface language reactively on the fly.

Shipped Languages

Key Capabilities

• Searchable Tactile Grid Selector: Built as a full-width, expandable UI component in app/auth.tsx. It displays each language in a distinct, high-impact tile featuring native labels, English translations, and country flags. An embedded real-time search input filters the grid instantly.
• Haptic Touch Integration: Utilizes native haptics (expo-haptics) to trigger medium and success haptic bumps on interaction, providing physical confirmation of language changes to the user.
• Modular Translation Registry: The dictionaries are separated cleanly into src/lib/translations/ (en.ts, hi.ts, ta.ts, global_dicts.ts) and unified in index.ts.
• Reactive App-Wide Translation: The selected locale is managed in the app-wide settings state (useApp()). Core auth screens and subsequent pages re-render reactively using the getAuthString() helper, keeping the active language synchronized across the entire user experience without requiring an app reload.

Appendix A — Original Planning Brief (Historical PWA Vision)

The content below is the original aspirational brief. Margi shipped as a native Expo Android app, not the Next.js PWA + sql.js described here. Sections 1–30 above are canonical. This appendix is retained for learning and provenance — it documents the architecture we explored, the reasoning, and the rejected sensor-mesh path.

A.1 Core innovation (three pillars)

flowchart LR
  P1["1. START TRIAGE CHATBOT
(AI + FSM)"] --> P2["2. TRAUMA-TIER ROUTING
(not nearest pin)"] --> P3["3. GOLDEN HOUR PACKET (GHP)
+ QR HUMAN RELAY"]

The three pillars (offline START triage, capability-based trauma-tier routing, and the GHP carried through dead zones by a human QR relay) survived from this vision into the shipped app — only the delivery platform changed from PWA to native Expo.

A.2 Original PWA system architecture

flowchart TB
    subgraph Client["Margi PWA (Next.js 14)"]
        Chat[Triage Chat UI]
        FSM[START Triage FSM]
        Router[Offline Spatial Router]
        GHP[GHP Builder + Compressor]
        QR[QR Generator / Scanner]
        IDB[(IndexedDB Relay Store)]
        SW[Service Worker / Serwist]
        SQL[(sql.js + emergency_seed.db)]
    end
    Chat --> FSM --> Router --> SQL
    FSM --> GHP --> QR --> IDB
    SW --> SQL

In the shipped app: Next.js PWA → Expo Router native; sql.js → expo-sqlite; IndexedDB relay → SecureStore + /relay; Serwist service worker → native offline (assets bundled in the APK); Web Speech API → expo-speech + optional YAMNet voice.

A.3 Original build-time data pipeline

OpenStreetMap -> Overpass API (nwr: hospitals, clinics, police, ambulance)
  -> ingestCorridors.py (parse names/phones/types, assign trauma_tier, tag corridor/state, manual verify CSV)
  -> emergency_seed.db -> bundled + submitted

This pipeline still exists under scripts/ (validated by poi-ingest.yml) and produces the verified NH48 pack, but the runtime app uses an inline seed in facilitiesDb.ts rather than loading the built DB file.

A.4 Original full runtime sequence

sequenceDiagram
    participant V as Victim Phone (Offline)
    participant FSM as START FSM
    participant DB as SQLite
    participant GHP as GHP Builder
    participant B as Bystander Phone
    participant SMS as 108 SMS
    V->>FSM: Start Emergency + GPS
    FSM->>FSM: Triage questions
    FSM->>DB: Query trauma-tier POIs
    DB-->>FSM: Ranked facilities
    FSM->>GHP: Build packet + hash
    GHP-->>V: Display QR + brief
    B->>V: Scan QR
    Note over B: Drives until signal returns
    B->>SMS: Auto-compose 108 message

End of Margi — Complete Replication Bible · Team NovaDrive · CoERS Road Safety Hackathon 2026.
Maintainer note: docs/CANON.md wins on any scope dispute. Update the Problem and Solution Log (Section 26) whenever a non-trivial bug is fixed, and rebuild the brief site with node docs/site/build-docs.js.