08 — Mobile UX revamp

Adopt the polished mobile UX from the reference app Elbaraaa/OneHealth as the new look-and-feel + screen flow for app/, without changing the backend: the DuckDB/DuckLake knowledge graph, the eight-agent orchestrator, the eleven MCP servers, the api/openapi.yaml contract, the privacy contract, and Supabase auth all stay exactly as they are. Only the Next.js front end changes.

Decisions (locked)

Fork Decision
Visual design Adopt Tailwind 3.4 + the reference’s teal design tokens, AppShell, and utility classes.
Framework baseline Upgrade app/ to Next.js 16 / React 19 (matches the reference). Static export + basePath must be preserved — this is a gated step (Phase 0).
Result screen Reuse the polished result-card layout, but bind it to the server’s TriageOutcome.next_action routing. No client-side risk scoring (the reference’s riskScoring.ts is rejected — see Guardrails).

Guardrails — what must NOT change

  1. api/openapi.yaml stays the source of truth. Any new field the polished forms collect (e.g. symptomStartDate, recentTravel, ongoingConcern) is added to the spec first, then npm run gen:api regenerates api-types.ts, then agents/.../api/models.py is re-validated. Never hand-edit api-types.ts.
  2. The submit path stays POST /v1/reports → FastAPI → DuckLake. The UI keeps calling createReport() (app/src/lib/api-client.ts). The intake write-path (agents/.../kg_writer.py) and MCP-backed agents are untouched.
  3. Privacy contract is load-bearing (CONTRIBUTING.md checklist):
  4. Static export + basePath: '/epihack-2026/app' must keep working (gh-pages deploy-app.yml, the VM nginx vhost, and the Ansible app role all build out/). This is the upgrade’s main risk.
  5. Anonymous-first. Auth stays optional (isAuthConfigured()); the whole report flow works signed-out.

Reference inventory → adopt / adapt / reject

Reference asset Disposition
tailwind.config.ts tokens (ink, public-teal, public-blue, soft-mint/sky, soft shadow) Adopt — becomes our design system.
app/globals.css utilities (.app-button, .choice-row, .phone-page/.phone-screen, .progress-track, .focus-ring) Adopt (merge into our globals.css).
components/AppShell.tsx + AppTopBar (390 px phone frame, back/title/user) Adopt — replaces our ad-hoc header/main shell. Add our AuthBadge into the top bar.
components/DomainSelection.tsx (feeling good/sick + domain toggles) Adapt — map to our report_type (human/animal/environmental); keep our anonymity defaults.
components/ReportForm.tsx (per-domain fields, progress bar, photo) Adapt heavily — keep the layout/progress UX, swap field sets to our event_class taxonomy + coarse-geo/exif steps; submit via createReport() not localStorage.
components/ProfileForm.tsx Adapt — keep UI, wire to attachProfile() PATCH /v1/reports/{id}/profile.
components/RiskResultCard.tsx + MitigationDetails.tsx (gauge + advice) Adapt — reuse layout; bind gauge to next_action/urgency, render copy + sources. Drop the score.
components/DashboardSummary.tsx, RecentReportsTable.tsx Adapt (Phase 6, optional) — feed from /v1/context ZCTA aggregations, not raw reports.
components/QuestionRenderer.tsx (generic input mapper) Adopt — useful to drive forms from an event-class schema.
lib/riskScoring.ts, lib/mockData.ts localStorage scoring Reject — replaced by server triage + our mock fixtures.
lib/types.ts report shapes Reject as-is — our ReportPayload/api-types.ts is the contract; map onto it.

Data-model mapping (reference → our contract)

Reference field Our ReportPayload / handling
domain human/animal/environment report_type human/animal/environmental
human symptoms[] symptoms: SymptomCategory[] + choose event_class (e.g. human.fever_chills)
symptomStartDate event_date (or new spec field — add to openapi first)
animal animalType, symptomsBehavior[] event_class (animal.*) + species + symptoms/notes
animalCount / multipleAnimalsAffected count
environment concernTypes[] event_class (env.*)
ongoingConcern, recentTravel, recentAnimalContact new optional spec fields (add to openapi, regen, validate) or fold into notes for v1
zipCode (raw) coarse_location.zip via normaliseZip(); keep GPS→grid_id path
photoAttached (flag only) real photo → stripExif() → multipart photo blob
client riskScore/group server TriageOutcome.next_action (+ urgency, copy, sources)

Phased work plan

Phase 0 — Framework upgrade + Tailwind (gated)

Phase 1 — Design system

Phase 2 — Screen flow

Phase 3 — Backend wiring (keep DuckLake + MCP)

Phase 4 — Privacy re-integration & governance

Phase 5 — Deploy reconciliation + verify

Phase 6 — Optional polish

Risks & mitigations

Acceptance checklist