Execution Roadmap — Dependency-Aware Phased Implementation¶

Status: Active planning document Date: 2026-04-17 Session: 41 Principle: Specs are non-negotiable before execution. UI/UX design identified where needed.

Inventory Summary¶

Total architectural surface: ~92 items across 6 categories.

Dependency Graph — What Blocks What¶

FOUNDATION LAYER (must exist before anything else)
├── DAO Layer (spec ready) ─────────────────────────┐
├── PostgreSQL RLS (spec ready) ────────────────────┤
├── LLM Fallback Gateway (spec ready) ─────────────┤
└── Monorepo Setup (no spec yet — NEEDS SPEC) ──────┤
                                                     │
INTAKE RESTRUCTURING (demo-critical)                 │
├── 5-Layer State Model (design complete) ──────────┼── depends on DAO Layer
├── Triage Agent + LangGraph (design complete) ─────┤     (clean data access)
├── Per-Layer Extractors ×5 (design complete) ──────┤
├── PFS/HSS/FMS Scoring (design complete) ──────────┤
├── Prompt Layer Contexts (design complete) ─────────┤
└── Progress Rail + Summary Panel UI ───────────────┤── NEEDS UI/UX DESIGN
                                                     │
MULTI-TENANCY (ADR-0018)                             │
├── Phase 0: Foundation (tenants, RBAC, Clerk orgs)─┼── depends on DAO + RLS
├── Phase 1: Provider Flow (onboarding, quoting) ───┤
├── Phase 2: Risk + MSO (video, consultation) ──────┤
├── Phase 3: Coordinators (assignment, tools) ──────┤
├── Phase 4: Payments + SLA ────────────────────────┤
├── Phase 5: Coordination Lifecycle ────────────────┤
└── Phase 6: Recovery Matching ─────────────────────┘
                                                     │
COORDINATOR TOOLING                                  │
├── Case Queue Dashboard ───────────────────────────┼── depends on Phase 3 + 5
├── Timeline & Transport Manager ───────────────────┤
├── Vendor Directory + Booking ─────────────────────┤── depends on Transport Spec
├── Escalation Panel ───────────────────────────────┤── depends on Phase 6
├── Coordinator Chat ───────────────────────────────┤── depends on ADR-0015
└── All coordinator UI ─────────────────────────────┤── NEEDS UI/UX DESIGN
                                                     │
PROVIDER PORTAL                                      │
├── Case Inbox ─────────────────────────────────────┼── depends on Phase 1
├── Quote Builder ──────────────────────────────────┤
├── Redacted EHR Viewer ────────────────────────────┤── depends on DAO redaction
├── Provider Performance Reports ───────────────────┤── depends on Phase 1 data
└── Provider portal UI ─────────────────────────────┤── NEEDS UI/UX DESIGN
                                                     │
TRANSPORT & SERVICES                                 │
├── coordinator_vendors table ──────────────────────┼── depends on Phase 5
├── coordinator_service_bookings table ─────────────┤
├── Travel Fitness Assessment ──────────────────────┤── depends on Intake Layer 3
├── Transport Panel (patient UI) ───────────────────┤── NEEDS UI/UX DESIGN
└── Vendor Management (coordinator UI) ─────────────┘── NEEDS UI/UX DESIGN
                                                     │
COST ESTIMATE                                        │
├── Estimate Generation Service ────────────────────┼── depends on Phase 1 quotes
├── Fee Model Configuration ────────────────────────┤     + Layer 5 PV
├── Estimate Display (patient UI) ──────────────────┤── NEEDS UI/UX DESIGN
└── Budget Comparison Logic ────────────────────────┘
                                                     │
MOBILE                                               │
├── Monorepo prerequisite ──────────────────────────┼── depends on Monorepo Setup
├── shared-core extraction ─────────────────────────┤
├── Expo app scaffold ──────────────────────────────┤
├── Chat + upload + notifications ──────────────────┤
└── Mobile patient UI ──────────────────────────────┤── NEEDS UI/UX DESIGN
                                                     │
PDF EXTRACTION                                       │
└── opendataloader-pdf shadow mode ─────────────────┼── independent (no blockers)

Critical Insight: The Least Friction Path¶

The naive approach is to execute ADR-0018 phases 0→1→2→3→4→5→6 sequentially. This is wrong. The demo-critical work (intake restructuring) doesn't depend on multi-tenancy. And multi-tenancy Phase 0 depends on DAO + RLS which are unrelated to intake.

The least friction path interleaves epics based on actual dependencies:

Execution Waves¶

Wave 0: Foundation (Weeks 1-2)¶

What: Infrastructure that every subsequent wave depends on.

Why these first: - DAO gives clean data access to every service built afterward. Without it, every new feature adds more inline SQLAlchemy that will need migration later. - RLS is defense-in-depth for multi-tenancy. Must exist before any provider/coordinator sees patient data. - LLM Gateway centralizes all LLM calls before we add 5 new extractors + Triage Agent.

UI/UX needed: None — pure backend. Specs needed: All ready. Execute directly.

Wave 1: Intake Restructuring (Weeks 3-6)¶

What: The demo-critical rewrite. 5-layer intake + Triage Agent + PFS/HSS/FMS.

UI/UX needed before execution: - Progress rail redesign (layers replacing current 8-flag model) - Layer summary cards (in-chat completion cards) - Summary panel redesign (layer-organized patient dashboard) - PFS/HSS/FMS display in match results

Specs needed: Design is complete. Each item needs an implementation spec (file-by-file change list, test plan, migration plan). Write specs in a batch before Wave 1 starts.

Note: Layer 2 (1.7) reuses the existing Clinical Context Agent — lowest risk. Layers 1, 3, 4, 5 are net-new extractors.

Wave 2: Frontend Monorepo + Patient UI (Weeks 5-8, overlaps with Wave 1)¶

What: Restructure frontend for multi-stakeholder apps. Ship intake UI changes.

UI/UX needed: Items 2.5, 2.6, 2.7, 2.8 need design before implementation. Specs needed: Monorepo setup (2.1-2.4) needs a spec. UI items need UI/UX design → spec → implementation.

Wave 3: Multi-Tenancy Foundation (Weeks 7-10, overlaps with Wave 2)¶

What: ADR-0018 Phases 0-1. Tenant infrastructure + provider onboarding.

UI/UX needed: - Provider portal (case inbox, quote builder) — NEEDS UI/UX DESIGN - Cost estimate display (patient-facing) — NEEDS UI/UX DESIGN - Admin portal (tenant management) — NEEDS UI/UX DESIGN

Specs needed: ADR-0018 has the architecture. Each item needs file-by-file implementation spec.

Wave 4: Coordination + Transport (Weeks 11-14)¶

What: ADR-0018 Phases 3+5, coordinator tooling, transport bookings.

UI/UX needed: - Full coordinator dashboard (case queue, timeline, vendor selector, escalation panel, chat) — NEEDS UI/UX DESIGN - Patient transport panel — NEEDS UI/UX DESIGN - Patient timeline cards — NEEDS UI/UX DESIGN

Specs needed: Transport spec is complete. Coordinator tooling needs implementation specs.

Wave 5: Provider Portal + MSO (Weeks 13-16, overlaps with Wave 4)¶

What: ADR-0018 Phases 1-2 frontend + MSO consultation.

UI/UX needed: 5.3, 5.4, 5.5, 5.6, 5.7 all need full UI/UX design.

Wave 6: Mobile + PDF + Polish (Weeks 15-20)¶

What: Mobile patient app, opendataloader-pdf integration, remaining gap items.

Wave 7: Payments + Recovery + Long-term (Weeks 19-24)¶

What: ADR-0018 Phases 4+6, subscription model exploration.

Items Requiring UI/UX Design Before Spec¶

These cannot be specced or built until UI/UX design is done.

Critical (blocks Waves 1-2)¶

Important (blocks Waves 4-5)¶

Nice to have (blocks Wave 6)¶

Spec Pipeline — What Needs Writing Before Each Wave¶

Before Wave 0 (write now — this week)¶

• DAO Layer: spec is ready, steer is ready. Execute directly.
• RLS: spec is ready. Execute directly.
• LLM Gateway: spec is ready, steer is ready. Execute directly.

Before Wave 1 (write in Week 2)¶

Write one consolidated implementation spec covering: - Layer state model (Alembic migration, patient_state schema) - Triage Agent LangGraph graph definition - 5 extractors (input/output schemas, model choice, structured output) - PFS/HSS/FMS scorers (pure functions, config loading, Flagsmith override) - Prompt layer contexts (7 YAML files) - Audit tables (3 Alembic migrations) - LangGraph checkpointing setup - PFS remediation behavior (agent prompt changes per band)

Before Wave 2 (write in Week 4, UI/UX in Week 3)¶

• Monorepo setup spec (pnpm workspace structure, CI/CD changes, Vercel config)
• UI/UX designs for progress rail, summary cards, summary panel, score display
• Implementation spec for each UI component

Before Wave 3 (write in Week 6)¶

• ADR-0018 Phase 0 implementation spec (tenants, RBAC, case_shares, state machine)
• ADR-0018 Phase 1 implementation spec (provider onboarding, quoting, forwarding)
• Cost estimate service implementation spec

Before Wave 4 (write in Week 10, UI/UX in Week 9)¶

• Coordinator tooling implementation spec
• Transport booking service implementation spec (mostly ready from deferred spec)
• UI/UX designs for coordinator dashboard, transport panel

Before Wave 5 (write in Week 12, UI/UX in Week 11)¶

• Provider portal implementation spec
• MSO consultation flow implementation spec
• Admin portal implementation spec
• UI/UX designs for all three portals

Before Wave 6 (write in Week 14)¶

• Mobile implementation spec (mostly ready from deferred spec)
• opendataloader integration spec (mostly ready from evaluation)
• Remaining feature specs (checklist, post-op manual, reports)

Items That Can Execute Independently (No Wave Dependencies)¶

These can be parallelized or slotted into any gap:

Risk Register¶

Timeline Summary¶

Week  1-2:   Wave 0 — DAO + RLS + LLM Gateway (foundation)
Week  3-6:   Wave 1 — Intake restructuring (backend, demo-critical)
Week  5-8:   Wave 2 — Monorepo + patient UI (overlaps Wave 1)
Week  7-10:  Wave 3 — Multi-tenancy Phases 0-1 (overlaps Wave 2)
Week 11-14:  Wave 4 — Coordination + transport
Week 13-16:  Wave 5 — Provider + MSO + coordinator portals
Week 15-20:  Wave 6 — Mobile + PDF + polish
Week 19-24:  Wave 7 — Payments + recovery + long-term

Total: ~24 weeks with overlapping waves
       ~20 weeks of active development (4 weeks overlap)

First demo-ready checkpoint: End of Week 8 (Waves 0-2 complete). Patient can go through 5-layer intake with PFS scoring, see layer-based progress, get matched with HSS/FMS scores.

Full platform checkpoint: End of Week 16 (Waves 0-5 complete). Multi-tenant, provider portal, coordinator dashboard, transport bookings, cost estimates.

Next Action¶

1. This week: Execute Wave 0 (DAO, RLS, LLM Gateway) — specs are ready
2. In parallel: UI/UX design for Wave 2 critical items (progress rail, summary cards, summary panel, score display)
3. Week 2: Write consolidated Wave 1 implementation spec
4. Week 3: Begin Wave 1 execution