Skip to content

Changelog — 2026-04-17 (Session 41)

Architecture & Design

Platform Restructuring Design (14 gaps → unified triage engine)

  • 17-part design spec (docs/specs/platform-restructuring-design.md) covering:
  • 5-layer dimensional intake (intent, medical, travel, logistics, financial)
  • A3 agent model (one triage agent + per-layer extractors, not one agent per layer)
  • PFS/HSS/FMS three-score system with configurable YAML weights
  • Layer completion criteria with adaptive routing (layers as dimensions, not strict sequence)
  • PFS remediation behavior (4 bands: ready/conditional/attention/not-ready)
  • Intent capture extraction schema with blended inference + explicit approach
  • Financial readiness with Patient Pricing Band qualification gates
  • Travel fitness two-track assessment and T1-T4 tier scoring
  • Logistics with visa auto-derivation and timeline feasibility
  • Consultation routing (MTC/Teleconsultation/MSO)
  • Cost estimate breakdown with configurable Curaway fee model
  • Frontend monorepo architecture (3 apps scaling to 7)
  • Coordinator tooling (case queue, timeline, vendor selector, escalation panel)
  • 3-tier consent-gated coordinator chat access with full audit trail
  • LangGraph runtime integration (checkpointing, parallel extractors, audit tables)
  • Prompt abstraction compatibility (layer_contexts replacing phase_contexts)

Coordinator Services Transport Spec

  • Ambulance/ground transport as first service type in generic Coordinator Services Framework
  • Hybrid model: scheduled transfers coordinator-assigned, emergency dispatch coordinator-managed
  • Transport tiers T1-T4 driven by travel fitness assessment
  • Vendor registry (coordinator_vendors) with migration path to full provider type
  • Coverage in both origin and destination countries, repatriation in scope

Execution Roadmap

  • 7-wave dependency-aware phased plan spanning ~24 weeks
  • Full sweep of 92 architectural items across ADRs, specs, design docs, gap report
  • Key insight: interleave epics based on dependencies, not sequential phase ordering
  • 12 items requiring UI/UX design before implementation identified

Mobile Architecture

  • React Native (Expo) chosen over SwiftUI/Flutter
  • Monorepo integration via packages/mobile-patient/
  • 40-60% code sharing with web via shared-core/
  • P0-P2 feature scope, App Store strategy

Evaluations

  • opendataloader-pdf: 0.928 table accuracy vs PyMuPDF 0.401 — recommended as shadow-mode dual-path
  • DeerFlow (ByteDance): full platform, overkill — stick with LangGraph directly
  • AgentScope (Alibaba): nothing LangGraph doesn't cover
  • notebooklm-py: consumer Google API wrapper, no HIPAA — skip
  • GSAP: saved for marketing site, not clinical apps

Implementation — Wave 0 DAO Layer (Phase 1)

New: Repository Layer (app/repositories/)

  • app/errors.py — DataStoreError hierarchy (6 classes, store-agnostic)
  • app/repositories/base.py — BaseRepository (tenant-scoped) + BaseUnscopedRepository
  • app/repositories/patient_repository.py — Patient CRUD with audit + events
  • app/repositories/case_repository.py — Case + Conversation with tenant-scoped case numbers (fixes global sequence bug)
  • app/repositories/fhir_repository.py — FHIR R4 resource CRUD with versioning
  • app/repositories/document_repository.py — Document lifecycle + supersede logic
  • app/repositories/provider_repository.py — Global catalog (BaseUnscopedRepository)

Service Migrations

  • case_service.py — all CRUD delegated to CaseRepository (-158 lines)
  • patient_service.py — reads + intake status delegated; encryption stays
  • fhir_service.py — reads delegated; create stays (dedup/versioning)
  • provider_service.py — reads delegated; Neo4j sync stays
  • document_service.py — reads delegated; R2/QStash stays

Tests

  • 34 new repository tests (tenant isolation, audit logging, case numbers, CI lint)
  • Fixed test_agent_pipeline.py stale mock (_check_existing_records)
  • Fixed tests/conftest.py — replaced drop/create with DELETE cleanup (eliminated 21 ERRORs)

Code Review Fixes

  • Restored SELECT FOR UPDATE + ValueError in CaseRepository.update_status
  • Added get_by_id_and_patient to FhirRepository (preserves triple-scoping)
  • Added _active_only to DocumentRepository (was returning soft-deleted docs)
  • Added is_active filter to ProviderRepository.get_by_id
  • Fixed count_by_patient to use actual COUNT query
  • Added generic Exception handler to _flush

Infrastructure — Claude Code Workspace

.claude Folder Setup

  • 5 commands: /session-start, /session-end, /spec-audit, /fix-issue, /deploy-check
  • 5 path-specific rules: backend-agents, backend-services, frontend, clinical, prompts
  • 2 hooks: pre-commit (branch + lint + PII + secrets), post-edit (auto-format)
  • settings.json: permissions (allow safe, deny destructive) + hook wiring

Design Skills (20 installed)

  • Emil Kowalski (emil-design-eng) — animation/motion philosophy
  • Impeccable (16 commands) — /polish, /audit, /animate, /typeset, /colorize, /critique, etc.
  • Google Stitch (2) — enhance-prompt, shadcn-ui
  • Brand context configured via .impeccable.md

MCP Servers

  • 21st.dev Magic — 1,400+ shadcn-compatible components via MCP (needs API key)

Spec Updates

  • DAO Layer spec — B- → A- (Session 41 tables, LangGraph checkpoint, migration order, RLS decision)
  • PostgreSQL RLS spec — D → A- (75 → 350+ lines: table inventory, migration SQL, rollback, tests, edge cases)
  • UI/UX Design Requirements — 12 items blocking implementation, prioritized by wave

Documentation

  • Terminology sweep: 13 POC→MVP, 5 Neon→Railway across 11 docs files
  • mkdocs.yml: added Deferred specs section, missing ADRs, changelog entries
  • docs/index.md: refreshed metrics (27+ tables, 87+ endpoints, 46+ flags, 19 ADRs)
  • Removed stale neon-postgres skill

PRs

  • #193 (merged) — Platform restructuring design + transport spec + tooling
  • #194 (merged) — DAO + RLS spec updates
  • #195 (open) — DAO Layer implementation + service migrations + tests