# udarachamidu/medtrace-ai architecture

> Architecture diagram of the GitHub repository udarachamidu/medtrace-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/udarachamidu/medtrace-ai
- Repository: https://github.com/udarachamidu/medtrace-ai

## Overview

#### Purpose and Operating Modes
MedTrace AI is a patient-record review application: it consolidates visits into timelines, medication and lab views, safety findings, and citation-backed record Q&A. It explicitly avoids diagnosis or treatment recommendations. The default reliable path is a synthetic, cached demo; a production mode connects the UI to Supabase and n8n AI workflows.
- `frontend/src/App.tsx`
- `frontend/src/lib/data-adapter.ts`
- `backend/fixtures/synthetic-demo.json`

#### Frontend Entry and Patient Workspace
The Vite/React client starts at `frontend/src/main.tsx`, routes between public/auth/patient views, and renders the main patient dashboard. `data-adapter` is the key boundary: it selects demo data versus configured remote data, insulating UI views from the source mode.
- `frontend/src/main.tsx`
- `frontend/src/lib/router.tsx`
- `frontend/src/pages/PatientDashboardPage.tsx`

#### Clinical Review Presentation
Dashboard components present the longitudinal timeline, medication/safety results, lab trends, and record-question interaction. The evidence drawer exposes the provenance required for a claim—source document, page, snippet, and confidence—rather than treating AI output as standalone fact.
- `frontend/src/components/DashboardViews.tsx`
- `frontend/src/components/EvidenceDrawer.tsx`
- `frontend/src/components/SafetyNotice.tsx`

#### Ingestion and AI Orchestration
n8n is the connected pipeline runtime. A patient-record workflow coordinates per-document processing, classification/extraction prompts, normalization, reconciliation, trends, safety checks, evidence verification, and persistence/query stages. Workflow templates are inactive until secrets, identity checks, and storage policies are configured.
- `backend/n8n/workflows/WF-01-process-patient-record.json`
- `backend/n8n/workflows/WF-02-process-one-document.json`
- `backend/n8n/workflows/WF-09-ask-record-question.json`

#### Clinical Processing Stages
Extracted records pass through medication and laboratory normalization, then longitudinal medication reconciliation and lab trend generation. Deterministic TypeScript safety rules evaluate allergies, duplicate therapies, dosage conflicts, and interactions; this provides a non-LLM safety boundary alongside prompt-driven extraction and verification.
- `backend/n8n/workflows/WF-03-normalize-medication.json`
- `backend/n8n/workflows/WF-07-safety-rules.json`
- `backend/src/rules/engine.ts`

#### Evidence, Confidence, and Prompt Contracts
Versioned prompts define LLM roles for document classification, clinical extraction, reconciliation, trends, evidence verification, and Q&A. Backend domain utilities model citations, confidence, dates, identity, ownership, and normalization so claims can remain attributable and uncertainty-aware.
- `backend/prompts/clinical-extractor/v1.md`
- `backend/prompts/evidence-verifier/v1.md`
- `backend/src/citations.ts`

#### Persistence, Security, and External Services
Supabase is the system of record and private document store, with migrations establishing schema/extensions, RLS, storage/RPC, vector-search support, and cross-patient integrity protections. The frontend uses only public Supabase/n8n configuration; n8n holds server-side Supabase credentials, webhook secrets, and OpenAI access. OpenAI is the intended LLM provider.
- `backend/supabase/migrations/202607300001_extensions_and_schema.sql`
- `backend/supabase/migrations/202607300002_rls_storage_and_rpc.sql`
- `backend/supabase/migrations/202607300003_cross_patient_integrity.sql`

Main entry points: [`frontend/src/components/DashboardViews.tsx`](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/DashboardViews.tsx) (Clinical dashboard views), [`backend/n8n/workflows/WF-09-ask-record-question.json`](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-09-ask-record-question.json) (Record Q&A workflow), [`backend/supabase/migrations/202607300001_extensions_and_schema.sql`](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/supabase/migrations/202607300001_extensions_and_schema.sql) (Supabase schema), [`frontend/src/pages/PatientDashboardPage.tsx`](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/pages/PatientDashboardPage.tsx) (Patient dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_app_entry["Vite entry<br/>React bootstrap<br/>[main.tsx]"]
  node_router["App router<br/>route layer<br/>[router.tsx]"]
  node_patient_dashboard["Patient dashboard<br/>workspace page"]
  node_data_adapter{{"Data adapter<br/>source boundary<br/>[data-adapter.ts]"}}
  node_dashboard_views["Clinical dashboard views<br/>presentation components<br/>[DashboardViews.tsx]"]
  node_evidence_drawer["Evidence drawer<br/>provenance UI<br/>[EvidenceDrawer.tsx]"]
  node_safety_notice["Safety notice<br/>safety UI<br/>[SafetyNotice.tsx]"]
end

subgraph group_pipeline["n8n processing"]
  node_record_workflow{{"Patient record workflow<br/>n8n orchestrator"}}
  node_document_workflow["Document processing<br/>n8n subworkflow"]
  node_normalization["Medication normalization<br/>n8n workflow"]
  node_safety_rules["Safety rules workflow<br/>n8n workflow"]
  node_record_qa["Record Q&amp;A workflow<br/>n8n workflow"]
end

subgraph group_backend["Backend contracts"]
  node_rule_engine{{"Deterministic rule engine<br/>TypeScript safety rules<br/>[engine.ts]"}}
  node_prompt_contracts["Versioned prompt contracts<br/>LLM prompts<br/>[v1.md]"]
  node_citation_contracts["Citation and confidence model<br/>domain utility<br/>[citations.ts]"]
end

subgraph group_platform["Data and AI services"]
  node_supabase_schema[("Supabase schema<br/>database migrations")]
  node_supabase_security[("Supabase security policies<br/>RLS and storage migrations")]
  node_openai["OpenAI<br/>LLM provider"]
end

node_synthetic_demo["Synthetic demo cache<br/>fixture data"]

node_app_entry -->|"starts"| node_router
node_router -->|"routes to"| node_patient_dashboard
node_patient_dashboard -->|"loads records through"| node_data_adapter
node_data_adapter -->|"demo mode reads"| node_synthetic_demo
node_data_adapter -->|"production mode reads"| node_supabase_schema
node_patient_dashboard -->|"renders"| node_dashboard_views
node_dashboard_views -->|"opens claim evidence"| node_evidence_drawer
node_dashboard_views -->|"presents findings"| node_safety_notice
node_dashboard_views -.->|"submits processing requests"| node_record_qa
node_record_workflow -->|"processes documents"| node_document_workflow
node_document_workflow -->|"sends extracted records"| node_normalization
node_normalization -->|"provides normalized medications"| node_safety_rules
node_safety_rules -->|"executes"| node_rule_engine
node_record_workflow -->|"persists and queries"| node_supabase_schema
node_record_qa -->|"retrieves patient evidence"| node_supabase_schema
node_record_qa -->|"formats cited claims"| node_citation_contracts
node_document_workflow -->|"uses extraction prompts"| node_prompt_contracts
node_record_qa -->|"uses Q&amp;A and verification prompts"| node_prompt_contracts
node_prompt_contracts -.->|"guides calls to"| node_openai
node_supabase_security -->|"secures data access"| node_supabase_schema

click node_synthetic_demo "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/fixtures/synthetic-demo.json"
click node_app_entry "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/main.tsx"
click node_router "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/lib/router.tsx"
click node_patient_dashboard "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/pages/PatientDashboardPage.tsx"
click node_data_adapter "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/lib/data-adapter.ts"
click node_dashboard_views "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/DashboardViews.tsx"
click node_evidence_drawer "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/EvidenceDrawer.tsx"
click node_safety_notice "https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/SafetyNotice.tsx"
click node_record_workflow "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-01-process-patient-record.json"
click node_document_workflow "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-02-process-one-document.json"
click node_normalization "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-03-normalize-medication.json"
click node_safety_rules "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-07-safety-rules.json"
click node_record_qa "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-09-ask-record-question.json"
click node_rule_engine "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/src/rules/engine.ts"
click node_prompt_contracts "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/prompts/clinical-extractor/v1.md"
click node_citation_contracts "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/src/citations.ts"
click node_supabase_schema "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/supabase/migrations/202607300001_extensions_and_schema.sql"
click node_supabase_security "https://github.com/udarachamidu/medtrace-ai/blob/main/backend/supabase/migrations/202607300002_rls_storage_and_rpc.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_router,node_patient_dashboard,node_data_adapter,node_dashboard_views,node_evidence_drawer,node_safety_notice toneBlue
class node_record_workflow,node_document_workflow,node_normalization,node_safety_rules,node_record_qa toneAmber
class node_rule_engine,node_prompt_contracts,node_citation_contracts toneMint
class node_supabase_schema,node_supabase_security,node_openai toneRose
class node_synthetic_demo toneNeutral
```

## Components

### React client

- [Vite entry](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/main.tsx): React bootstrap · `frontend/src/main.tsx`
- [App router](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/lib/router.tsx): route layer · Routes public, authentication, and patient views. · `frontend/src/lib/router.tsx`
- [Patient dashboard](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/pages/PatientDashboardPage.tsx): workspace page · `frontend/src/pages/PatientDashboardPage.tsx`
- [Data adapter](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/lib/data-adapter.ts): source boundary · Selects demo or configured remote data for UI views. · `frontend/src/lib/data-adapter.ts`
- [Clinical dashboard views](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/DashboardViews.tsx): presentation components · Shows timeline, medications, safety findings, labs, and record Q&A. · `frontend/src/components/DashboardViews.tsx`
- [Evidence drawer](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/EvidenceDrawer.tsx): provenance UI · Shows source, page, snippet, and confidence for claims. · `frontend/src/components/EvidenceDrawer.tsx`
- [Safety notice](https://github.com/udarachamidu/medtrace-ai/blob/main/frontend/src/components/SafetyNotice.tsx): safety UI · `frontend/src/components/SafetyNotice.tsx`

### n8n processing

- [Patient record workflow](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-01-process-patient-record.json): n8n orchestrator · Coordinates per-document processing and persistence stages. · `backend/n8n/workflows/WF-01-process-patient-record.json`
- [Document processing](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-02-process-one-document.json): n8n subworkflow · Classifies and extracts each patient document. · `backend/n8n/workflows/WF-02-process-one-document.json`
- [Medication normalization](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-03-normalize-medication.json): n8n workflow · Normalizes extracted medication records. · `backend/n8n/workflows/WF-03-normalize-medication.json`
- [Safety rules workflow](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-07-safety-rules.json): n8n workflow · Runs deterministic medication safety evaluation. · `backend/n8n/workflows/WF-07-safety-rules.json`
- [Record Q&A workflow](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/n8n/workflows/WF-09-ask-record-question.json): n8n workflow · Answers record questions with evidence verification. · `backend/n8n/workflows/WF-09-ask-record-question.json`

### Backend contracts

- [Deterministic rule engine](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/src/rules/engine.ts): TypeScript safety rules · Checks allergies, duplicate therapies, dose conflicts, and interactions. · `backend/src/rules/engine.ts`
- [Versioned prompt contracts](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/prompts/clinical-extractor/v1.md): LLM prompts · Defines extraction, verification, reconciliation, trends, and Q&A roles. · `backend/prompts/clinical-extractor/v1.md`
- [Citation and confidence model](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/src/citations.ts): domain utility · Keeps claims attributable and uncertainty-aware. · `backend/src/citations.ts`

### Data and AI services

- [Supabase schema](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/supabase/migrations/202607300001_extensions_and_schema.sql): database migrations · Establishes record schema, extensions, and vector support. · `backend/supabase/migrations/202607300001_extensions_and_schema.sql`
- [Supabase security policies](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/supabase/migrations/202607300002_rls_storage_and_rpc.sql): RLS and storage migrations · Applies RLS, storage/RPC controls, and cross-patient protections. · `backend/supabase/migrations/202607300002_rls_storage_and_rpc.sql`
- **OpenAI**: LLM provider · Used by n8n with server-side credentials.

### Other components

- [Synthetic demo cache](https://github.com/udarachamidu/medtrace-ai/blob/main/backend/fixtures/synthetic-demo.json): fixture data · Default reliable patient-record dataset. · `backend/fixtures/synthetic-demo.json`

## Connections

- Vite entry → App router: starts
- App router → Patient dashboard: routes to
- Patient dashboard → Data adapter: loads records through
- Data adapter → Synthetic demo cache: demo mode reads
- Data adapter → Supabase schema: production mode reads
- Patient dashboard → Clinical dashboard views: renders
- Clinical dashboard views → Evidence drawer: opens claim evidence
- Clinical dashboard views → Safety notice: presents findings
- Clinical dashboard views → Record Q&A workflow: submits processing requests
- Patient record workflow → Document processing: processes documents
- Document processing → Medication normalization: sends extracted records
- Medication normalization → Safety rules workflow: provides normalized medications
- Safety rules workflow → Deterministic rule engine: executes
- Patient record workflow → Supabase schema: persists and queries
- Record Q&A workflow → Supabase schema: retrieves patient evidence
- Record Q&A workflow → Citation and confidence model: formats cited claims
- Document processing → Versioned prompt contracts: uses extraction prompts
- Record Q&A workflow → Versioned prompt contracts: uses Q&A and verification prompts
- Versioned prompt contracts → OpenAI: guides calls to
- Supabase security policies → Supabase schema: secures data access