# kamalesakki/medcode architecture

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

- Interactive diagram: https://gitdiagram.com/kamalesakki/medcode
- Repository: https://github.com/kamalesakki/medcode

## Overview

MedCode AI is a clinical documentation and revenue-cycle assistant. Its principal workflow takes a consultation or clinical text into a session, extracts a transcript and structured SOAP note, suggests ICD-10/CPT codes, runs claim checks, and leaves final decisions to human reviewers with an audit trail. Supporting capabilities include authentication, case management, dashboards, notifications, performance reporting, and Zoom/Teams integrations. The README documents the end-to-end stages; sampled source confirms session intake, AI extraction, persistence, and review/audit behavior. Other router internals were not sampled, so their detailed calls are not asserted.

Main entry points: [`backend/main.py`](https://github.com/kamalesakki/medcode/blob/main/backend/main.py) (FastAPI API), [`backend/routers/sessions.py`](https://github.com/kamalesakki/medcode/blob/main/backend/routers/sessions.py) (Session Intake), [`backend/database.py`](https://github.com/kamalesakki/medcode/blob/main/backend/database.py) (Database Access), [`backend/routers/reviews.py`](https://github.com/kamalesakki/medcode/blob/main/backend/routers/reviews.py) (Human Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Clinical Workflow"]
  node_sessions["Session Intake<br/>[sessions.py]"]
  node_transcripts["Transcripts<br/>[transcripts.py]"]
  node_notes["Clinical Notes<br/>[clinical_notes.py]"]
  node_coding["Code Suggestions<br/>[coding.py]"]
  node_scrubbing["Claim Scrubbing<br/>[scrubbing.py]"]
  node_reviews["Human Review<br/>[reviews.py]"]
  node_dashboard["Dashboard Metrics<br/>[dashboard.py]"]
  node_assistant["Assistant<br/>[assistant.py]"]
end

subgraph group_ai["AI Processing"]
  node_ai_engine["AI Engine<br/>[ai_service.py]"]
end

subgraph group_platform["Platform Services"]
  node_api["FastAPI API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_zoom["Zoom Connector<br/>[zoom_service.py]"]
  node_teams["Teams Connector<br/>[teams_service.py]"]
  node_support_routers["Operations APIs"]
  node_config["Configuration<br/>[config.py]"]
  node_schemas["API Schemas"]
end

subgraph group_persistence["Persistence"]
  node_db_layer["Database Access<br/>[database.py]"]
  node_clinical_records[("Clinical Records")]
  node_code_records[("Code Suggestions<br/>[code_suggestion.py]")]
  node_audit_records[("Review Audits<br/>[review_audit.py]")]
end

node_clinician(("Clinical User"))

node_clinician -->|"uses"| node_api
node_api -->|"routes to"| node_sessions
node_api -->|"routes to"| node_transcripts
node_api -->|"routes to"| node_notes
node_api -->|"routes to"| node_coding
node_api -->|"routes to"| node_scrubbing
node_api -->|"routes to"| node_reviews
node_api -->|"routes to"| node_dashboard
node_api -->|"routes to"| node_assistant
node_sessions -->|"extracts clinical data"| node_ai_engine
node_sessions -->|"stores case data"| node_clinical_records
node_sessions -->|"queries and writes"| node_db_layer
node_sessions -.->|"captures transcript"| node_transcripts
node_transcripts -->|"informs extraction"| node_notes
node_notes -->|"informs suggestions"| node_coding
node_coding -->|"provides codes"| node_scrubbing
node_scrubbing -->|"queues for review"| node_reviews
node_reviews -->|"updates decisions"| node_code_records
node_reviews -->|"records actions"| node_audit_records
node_reviews -->|"commits changes"| node_db_layer
node_dashboard -->|"aggregates metrics"| node_clinical_records
node_assistant -->|"reads and writes"| node_clinical_records
node_assistant -->|"checks identity"| node_auth
node_sessions -->|"checks identity"| node_auth
node_api -->|"serves authentication"| node_auth
node_api -->|"routes to"| node_support_routers
node_support_routers -->|"uses connector"| node_zoom
node_support_routers -->|"uses connector"| node_teams
node_zoom -->|"reads settings"| node_config
node_teams -->|"uses integration"| node_zoom
node_db_layer -->|"reads database settings"| node_config
node_clinical_records -->|"maps tables"| node_db_layer
node_code_records -->|"maps table"| node_db_layer
node_audit_records -->|"maps table"| node_db_layer
node_api -.->|"validates API data"| node_schemas
node_ai_engine -->|"reads AI settings"| node_config

click node_api "https://github.com/kamalesakki/medcode/blob/main/backend/main.py"
click node_sessions "https://github.com/kamalesakki/medcode/blob/main/backend/routers/sessions.py"
click node_transcripts "https://github.com/kamalesakki/medcode/blob/main/backend/routers/transcripts.py"
click node_notes "https://github.com/kamalesakki/medcode/blob/main/backend/routers/clinical_notes.py"
click node_coding "https://github.com/kamalesakki/medcode/blob/main/backend/routers/coding.py"
click node_scrubbing "https://github.com/kamalesakki/medcode/blob/main/backend/routers/scrubbing.py"
click node_reviews "https://github.com/kamalesakki/medcode/blob/main/backend/routers/reviews.py"
click node_dashboard "https://github.com/kamalesakki/medcode/blob/main/backend/routers/dashboard.py"
click node_assistant "https://github.com/kamalesakki/medcode/blob/main/backend/routers/assistant.py"
click node_ai_engine "https://github.com/kamalesakki/medcode/blob/main/backend/services/ai_service.py"
click node_auth "https://github.com/kamalesakki/medcode/blob/main/backend/services/auth_service.py"
click node_zoom "https://github.com/kamalesakki/medcode/blob/main/backend/services/zoom_service.py"
click node_teams "https://github.com/kamalesakki/medcode/blob/main/backend/services/teams_service.py"
click node_support_routers "https://github.com/kamalesakki/medcode/tree/main/backend/routers"
click node_config "https://github.com/kamalesakki/medcode/blob/main/backend/config.py"
click node_db_layer "https://github.com/kamalesakki/medcode/blob/main/backend/database.py"
click node_clinical_records "https://github.com/kamalesakki/medcode/tree/main/backend/models"
click node_code_records "https://github.com/kamalesakki/medcode/blob/main/backend/models/code_suggestion.py"
click node_audit_records "https://github.com/kamalesakki/medcode/blob/main/backend/models/review_audit.py"
click node_schemas "https://github.com/kamalesakki/medcode/tree/main/backend/schemas"

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_sessions,node_transcripts,node_notes,node_coding,node_scrubbing,node_reviews,node_dashboard,node_assistant,node_clinician toneBlue
class node_ai_engine toneAmber
class node_api,node_auth,node_zoom,node_teams,node_support_routers,node_config,node_schemas toneMint
class node_db_layer,node_clinical_records,node_code_records,node_audit_records toneRose
```

## Components

### Clinical Workflow

- [Session Intake](https://github.com/kamalesakki/medcode/blob/main/backend/routers/sessions.py): `backend/routers/sessions.py`
- [Transcripts](https://github.com/kamalesakki/medcode/blob/main/backend/routers/transcripts.py): `backend/routers/transcripts.py`
- [Clinical Notes](https://github.com/kamalesakki/medcode/blob/main/backend/routers/clinical_notes.py): `backend/routers/clinical_notes.py`
- [Code Suggestions](https://github.com/kamalesakki/medcode/blob/main/backend/routers/coding.py): `backend/routers/coding.py`
- [Claim Scrubbing](https://github.com/kamalesakki/medcode/blob/main/backend/routers/scrubbing.py): `backend/routers/scrubbing.py`
- [Human Review](https://github.com/kamalesakki/medcode/blob/main/backend/routers/reviews.py): `backend/routers/reviews.py`
- [Dashboard Metrics](https://github.com/kamalesakki/medcode/blob/main/backend/routers/dashboard.py): `backend/routers/dashboard.py`
- [Assistant](https://github.com/kamalesakki/medcode/blob/main/backend/routers/assistant.py): `backend/routers/assistant.py`

### AI Processing

- [AI Engine](https://github.com/kamalesakki/medcode/blob/main/backend/services/ai_service.py): `backend/services/ai_service.py`

### Platform Services

- [FastAPI API](https://github.com/kamalesakki/medcode/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/kamalesakki/medcode/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Zoom Connector](https://github.com/kamalesakki/medcode/blob/main/backend/services/zoom_service.py): `backend/services/zoom_service.py`
- [Teams Connector](https://github.com/kamalesakki/medcode/blob/main/backend/services/teams_service.py): `backend/services/teams_service.py`
- [Operations APIs](https://github.com/kamalesakki/medcode/tree/main/backend/routers): `backend/routers`
- [Configuration](https://github.com/kamalesakki/medcode/blob/main/backend/config.py): `backend/config.py`
- [API Schemas](https://github.com/kamalesakki/medcode/tree/main/backend/schemas): `backend/schemas`

### Persistence

- [Database Access](https://github.com/kamalesakki/medcode/blob/main/backend/database.py): `backend/database.py`
- [Clinical Records](https://github.com/kamalesakki/medcode/tree/main/backend/models): `backend/models`
- [Code Suggestions](https://github.com/kamalesakki/medcode/blob/main/backend/models/code_suggestion.py): `backend/models/code_suggestion.py`
- [Review Audits](https://github.com/kamalesakki/medcode/blob/main/backend/models/review_audit.py): `backend/models/review_audit.py`

### Other components

- **Clinical User**

## Connections

- Clinical User → FastAPI API: uses (evidence: `README.md`)
- FastAPI API → Session Intake: routes to (evidence: `backend/main.py`)
- FastAPI API → Transcripts: routes to (evidence: `backend/main.py`)
- FastAPI API → Clinical Notes: routes to (evidence: `backend/main.py`)
- FastAPI API → Code Suggestions: routes to (evidence: `backend/main.py`)
- FastAPI API → Claim Scrubbing: routes to (evidence: `backend/main.py`)
- FastAPI API → Human Review: routes to (evidence: `backend/main.py`)
- FastAPI API → Dashboard Metrics: routes to (evidence: `backend/main.py`)
- FastAPI API → Assistant: routes to (evidence: `backend/main.py`)
- Session Intake → AI Engine: extracts clinical data (evidence: `backend/routers/sessions.py`)
- Session Intake → Clinical Records: stores case data (evidence: `backend/routers/sessions.py`)
- Session Intake → Database Access: queries and writes (evidence: `backend/routers/sessions.py`)
- Session Intake → Transcripts: captures transcript
- Transcripts → Clinical Notes: informs extraction (evidence: `README.md`)
- Clinical Notes → Code Suggestions: informs suggestions (evidence: `README.md`)
- Code Suggestions → Claim Scrubbing: provides codes (evidence: `README.md`)
- Claim Scrubbing → Human Review: queues for review (evidence: `README.md`)
- Human Review → Code Suggestions: updates decisions (evidence: `backend/routers/reviews.py`)
- Human Review → Review Audits: records actions (evidence: `backend/routers/reviews.py`)
- Human Review → Database Access: commits changes (evidence: `backend/routers/reviews.py`)
- Dashboard Metrics → Clinical Records: aggregates metrics (evidence: `backend/routers/dashboard.py`)
- Assistant → Clinical Records: reads and writes (evidence: `backend/routers/assistant.py`)
- Assistant → Authentication: checks identity (evidence: `backend/routers/assistant.py`)
- Session Intake → Authentication: checks identity (evidence: `backend/routers/sessions.py`)
- FastAPI API → Authentication: serves authentication (evidence: `backend/main.py`)
- FastAPI API → Operations APIs: routes to (evidence: `backend/main.py`)
- Operations APIs → Zoom Connector: uses connector (evidence: `backend/routers/zoom.py`)
- Operations APIs → Teams Connector: uses connector (evidence: `backend/routers/teams.py`)
- Zoom Connector → Configuration: reads settings (evidence: `backend/services/zoom_service.py`)
- Teams Connector → Zoom Connector: uses integration (evidence: `backend/services/teams_service.py`)
- Database Access → Configuration: reads database settings (evidence: `backend/database.py`)
- Clinical Records → Database Access: maps tables (evidence: `backend/models/session.py`)
- Code Suggestions → Database Access: maps table (evidence: `backend/models/code_suggestion.py`)
- Review Audits → Database Access: maps table (evidence: `backend/models/review_audit.py`)
- FastAPI API → API Schemas: validates API data
- AI Engine → Configuration: reads AI settings (evidence: `backend/services/ai_service.py`)
