Procedure Requirements — Implementation Audit & Sprint Plan¶

Audit Date: 2026-04-03 Status: Partial implementation — read layer complete, write layer + seed data gaps

What's Built (Production)¶

Neo4j Knowledge Graph¶

DiagnosticTest (25 nodes)
  ├── blood_work (10): CBC, BMP, Coagulation, Blood Type, HbA1c, Urinalysis, CRP, ESR, Thyroid, Vitamin D
  ├── cardiac (5): ECG, Echo, Stress Test, Coronary Angiogram, CT Coronary
  ├── imaging (5): Chest X-Ray, MRI Knee, X-Ray Knee, CT Chest, DEXA
  ├── pulmonary (1): PFT
  ├── clinical_clearance (3): Anesthesia Eval, Cardiology Clearance, Dental Clearance
  └── infection_screen (1): MRSA Swab

REQUIRES_TEST (33 relationships) — procedure → test
  Properties: validity_days, priority, source_acceptance, on_site_required,
              source_note, condition_note, timing_note

REQUIRES_FOR_PROCEDURE (12 relationships) — provider → test (overrides)
  Properties: procedure, override_validity_days, override_priority,
              override_source_acceptance, override_on_site_required, source_note
  Providers: Apollo Chennai (5), Bumrungrad (3), Acibadem (2), others (2)

Backend Services¶

API Endpoint¶

GET /api/v1/procedures/{procedure_slug}/requirements?provider_id=

Returns ProcedureRequirementsResponse with TestRequirement objects containing: test_name, category, priority, validity_days, source_acceptance, on_site_required, source_note, condition_note, timing_note, is_provider_override

Frontend¶

RequirementsChecklist.tsx — Full UI showing priority groups, validity badges, source labels, on-site flags, provider override indicators.

Schemas¶

Backend (routers/procedures.py): - TestRequirement — all properties including source_acceptance, on_site_required, is_provider_override - ProcedureRequirementsResponse — counts by priority

Frontend (types/api.ts): - Matching TypeScript interfaces

What's Missing¶

Gap 1: REQUIRES_FOR_PROCEDURE Creation Function (HIGH)¶

What: No link_provider_procedure_override() function in graph_service.py Impact: Provider-specific test requirement overrides cannot be created programmatically Evidence: The 12 existing overrides were created manually via Cypher Fix:

def link_provider_procedure_override(
    provider_slug: str,
    test_code: str,
    procedure_code: str,
    override_validity_days: int | None = None,
    override_priority: str | None = None,
    override_source_acceptance: str | None = None,
    override_on_site_required: bool | None = None,
    source_note: str | None = None,
) -> bool:

Gap 2: Override Management API Endpoints (HIGH)¶

What: No POST/PATCH/DELETE endpoints for managing provider overrides Impact: Provider onboarding cannot self-serve test requirements Fix:

POST   /api/v1/providers/{id}/procedures/{code}/requirements/{test_code}
PATCH  /api/v1/providers/{id}/procedures/{code}/requirements/{test_code}
DELETE /api/v1/providers/{id}/procedures/{code}/requirements/{test_code}

Gap 3: Incomplete REQUIRES_TEST Seed Data (MEDIUM)¶

What: Only 2 of 22 procedures have REQUIRES_TEST relationships seeded (TKR + CABG) Impact: 20 procedures have no test requirements in Neo4j — checklist falls back to PostgreSQL defaults Data needed:

Effort: 6h (research + seed script)

Gap 4: PostgreSQL ↔ Neo4j Requirement Disconnect (MEDIUM)¶

What: Rich test metadata (validity_days, source_acceptance, on_site_required) lives only in Neo4j. PostgreSQL procedure_requirements table has required_documents and required_tests as simple string arrays. Impact: - Agents read from PostgreSQL (via case_service.get_procedure_requirements) — get simple names, miss rich metadata - Document checklist reads from PostgreSQL — gets basic requirement names, not validity/source rules - GDPR data exports include PostgreSQL but not Neo4j — requirement context lost Fix options: - A) Sync rich metadata from Neo4j to PostgreSQL JSONB fields - B) Have agents query Neo4j directly via graph_service.get_procedure_requirements_enhanced() - C) Denormalize: store requirement metadata in PostgreSQL procedure_requirements.required_documents JSONB Recommendation: Option B for now (lowest effort), Option C long-term Effort: 3h for Option B, 8h for Option C

Gap 5: Seed Property Name Mismatch (LOW)¶

What: Seed script uses timing and notes but queries expect timing_note and condition_note Impact: 17/33 relationships have timing_note, 11/33 have condition_note — some missing due to wrong key names Fix: Update seed script to use correct property names Effort: 1h

Gap 6: No Override Seed Data (LOW)¶

What: 12 provider overrides exist in production with no seed script path Impact: If Neo4j is reset, overrides are lost — no reproducible creation path Fix: Add PROVIDER_OVERRIDES dict to seed_graph.py Effort: 2h

Sprint Plan¶

Sprint A: Foundation (8h)¶

1. Add link_provider_procedure_override() to graph_service.py — 2h
2. Add POST/PATCH/DELETE override endpoints — 4h
3. Fix seed property name mismatch (timing → timing_note) — 1h
4. Add override seed data to seed_graph.py — 1h

Sprint B: Data Completeness (8h)¶

1. Research and seed REQUIRES_TEST for all 22 procedures — 6h
2. Have agents query Neo4j for rich requirements (Option B) — 2h

Sprint C: Full Integration (6h)¶

1. Denormalize requirement metadata to PostgreSQL (Option C) — 4h
2. Update document checklist to show validity/source from Neo4j — 2h

Property Reference¶

DiagnosticTest Node Properties¶

REQUIRES_TEST Relationship Properties¶

REQUIRES_FOR_PROCEDURE Override Properties¶

source_acceptance Values¶