# shisir2024/cureo_medi architecture

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

- Interactive diagram: https://gitdiagram.com/shisir2024/cureo_medi
- Repository: https://github.com/shisir2024/cureo_medi

## Overview

#### Purpose and Runtime

MediAssist AI is a health-information assistant that accepts consultation input, applies safety-oriented triage and specialist analysis, and returns structured JSON. The Python backend is the primary runtime; static HTML/CSS/JavaScript pages provide patient, learning, and doctor-facing interfaces. Deployment is indicated by `Procfile`; local startup is supported by `run.sh`.

Paths: `backend/main.py`, `Procfile`, `frontend/consultation.html`

#### API Entry and Session Boundaries

The backend application is initialized in `backend/main.py` and exposes domain routers for agent execution, authentication, consultations, and doctor workflows. Route modules form the HTTP boundary between frontend clients and application services. WebSocket state/connection handling is separated for real-time interactions.

Paths: `backend/main.py`, `backend/routers/consult_routes.py`, `backend/ws_manager.py`

#### Authentication and Persistence

Authentication is isolated from consultation logic, while database access is centralized behind a dedicated module. This creates a boundary for user identity, protected doctor/patient workflows, and persisted consultation-related records without coupling agents directly to storage.

Paths: `backend/auth.py`, `backend/database.py`, `backend/routers/auth_routes.py`

#### Orchestration Pipeline

`backend/orchestrator.py` is the central control-flow layer. It coordinates specialized agents rather than exposing their implementation details to routes. The expected flow starts with triage, proceeds to symptom analysis, conditionally invokes diagnosis/treatment/referral and visualization/scoring agents, then compiles a final response.

Paths: `backend/orchestrator.py`, `backend/agents/triage.py`, `backend/agents/report.py`

#### Safety and Emergency Handling

Triage is the first decision stage and governs safety-sensitive branching. Emergency cases are escalated through symptom analysis and visualization-oriented outputs, with an emergency fallback path rather than routine diagnostic/treatment progression. Global safety behavior and response framing are likely shared through the system prompt and agent prompts.

Paths: `backend/agents/triage.py`, `backend/agents/symptom_analyzer.py`, `backend/system_prompt.py`

#### Specialist Agent Layer

Each clinical-information concern is encapsulated as an agent: diagnosis, treatment, referral, vitals, symptom web, health score, heatmap, radar, and comparison. This supports parallel or selectively invoked analysis stages under orchestrator control. The report agent is the aggregation boundary that converts heterogeneous agent results into the final structured JSON contract.

Paths: `backend/agents/diagnosis.py`, `backend/agents/treatment.py`, `backend/agents/health_score.py`

#### LLM and Client Integration

LLM provider access is centralized in `backend/llm.py`, keeping model/API-key integration outside individual route handlers and likely reusable across agents. The frontend uses standalone pages and browser JavaScript; consultation and doctor portal pages are distinct clients of backend APIs.

Paths: `backend/llm.py`, `frontend/consultation.js`, `frontend/doctor.js`

Main entry points: [`backend/main.py`](https://github.com/shisir2024/cureo_medi/blob/main/backend/main.py) (Backend application), [`backend/routers/consult_routes.py`](https://github.com/shisir2024/cureo_medi/blob/main/backend/routers/consult_routes.py) (Consultation routes), [`backend/agents/report.py`](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/report.py) (Report compiler), [`backend/agents/triage.py`](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/triage.py) (Safety triage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Browser clients"]
  node_consultation_page["Consultation UI<br/>static page<br/>[consultation.html]"]
  node_consultation_client["Consultation client<br/>browser JavaScript<br/>[consultation.js]"]
  node_doctor_client["Doctor portal client<br/>browser JavaScript<br/>[doctor.js]"]
end

subgraph group_api["Backend boundary"]
  node_app["Backend application<br/>Python API app<br/>[main.py]"]
  node_consult_routes["Consultation routes<br/>HTTP router<br/>[consult_routes.py]"]
  node_auth_routes["Authentication routes<br/>HTTP router<br/>[auth_routes.py]"]
  node_websocket_manager["WebSocket manager<br/>connection state<br/>[ws_manager.py]"]
end

subgraph group_pipeline["Clinical pipeline"]
  node_orchestrator["Agent orchestrator<br/>control flow<br/>[orchestrator.py]"]
  node_triage["Safety triage<br/>agent<br/>[triage.py]"]
  node_symptom_analyzer["Symptom analysis<br/>agent"]
  node_diagnosis["Diagnosis agent<br/>specialist agent<br/>[diagnosis.py]"]
  node_treatment["Treatment agent<br/>specialist agent<br/>[treatment.py]"]
  node_health_score["Health scoring<br/>specialist agent<br/>[health_score.py]"]
  node_report["Report compiler<br/>response aggregation<br/>[report.py]"]
end

subgraph group_platform["Platform services"]
  node_auth["Identity service<br/>authentication<br/>[auth.py]"]
  node_database[("Persistence<br/>database access<br/>[database.py]")]
  node_llm["LLM integration<br/>provider gateway<br/>[llm.py]"]
  node_system_prompt["Safety prompt<br/>shared prompt<br/>[system_prompt.py]"]
  node_deployment{{"Process deployment<br/>deployment entrypoint"}}
  node_local_start["Local startup<br/>startup script<br/>[run.sh]"]
end

node_consultation_page -->|"loads"| node_consultation_client
node_consultation_client -->|"HTTP"| node_consult_routes
node_doctor_client -->|"doctor APIs"| node_app
node_app -->|"mounts"| node_consult_routes
node_app -->|"mounts"| node_auth_routes
node_app -->|"real-time state"| node_websocket_manager
node_auth_routes -->|"authenticates"| node_auth
node_auth -->|"user records"| node_database
node_consult_routes -->|"consultation request"| node_orchestrator
node_consult_routes -->|"consultation records"| node_database
node_orchestrator -->|"first stage"| node_triage
node_triage -->|"analyze or emergency path"| node_symptom_analyzer
node_symptom_analyzer -.->|"routine analysis"| node_diagnosis
node_symptom_analyzer -.->|"routine analysis"| node_treatment
node_symptom_analyzer -.->|"scoring"| node_health_score
node_triage -.->|"emergency fallback"| node_report
node_diagnosis -->|"findings"| node_report
node_treatment -->|"guidance"| node_report
node_health_score -->|"score"| node_report
node_report -->|"structured JSON"| node_consult_routes
node_orchestrator -->|"model access"| node_llm
node_triage -.->|"safety framing"| node_system_prompt
node_deployment -->|"runs"| node_app
node_local_start -->|"starts"| node_app

click node_consultation_page "https://github.com/shisir2024/cureo_medi/blob/main/frontend/consultation.html"
click node_consultation_client "https://github.com/shisir2024/cureo_medi/blob/main/frontend/consultation.js"
click node_doctor_client "https://github.com/shisir2024/cureo_medi/blob/main/frontend/doctor.js"
click node_app "https://github.com/shisir2024/cureo_medi/blob/main/backend/main.py"
click node_consult_routes "https://github.com/shisir2024/cureo_medi/blob/main/backend/routers/consult_routes.py"
click node_auth_routes "https://github.com/shisir2024/cureo_medi/blob/main/backend/routers/auth_routes.py"
click node_websocket_manager "https://github.com/shisir2024/cureo_medi/blob/main/backend/ws_manager.py"
click node_auth "https://github.com/shisir2024/cureo_medi/blob/main/backend/auth.py"
click node_database "https://github.com/shisir2024/cureo_medi/blob/main/backend/database.py"
click node_orchestrator "https://github.com/shisir2024/cureo_medi/blob/main/backend/orchestrator.py"
click node_triage "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/triage.py"
click node_symptom_analyzer "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/symptom_analyzer.py"
click node_diagnosis "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/diagnosis.py"
click node_treatment "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/treatment.py"
click node_health_score "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/health_score.py"
click node_report "https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/report.py"
click node_llm "https://github.com/shisir2024/cureo_medi/blob/main/backend/llm.py"
click node_system_prompt "https://github.com/shisir2024/cureo_medi/blob/main/backend/system_prompt.py"
click node_deployment "https://github.com/shisir2024/cureo_medi/blob/main/Procfile"
click node_local_start "https://github.com/shisir2024/cureo_medi/blob/main/run.sh"

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_consultation_page,node_consultation_client,node_doctor_client toneBlue
class node_app,node_consult_routes,node_auth_routes,node_websocket_manager toneAmber
class node_orchestrator,node_triage,node_symptom_analyzer,node_diagnosis,node_treatment,node_health_score,node_report toneMint
class node_auth,node_database,node_llm,node_system_prompt,node_deployment,node_local_start toneRose
```

## Components

### Browser clients

- [Consultation UI](https://github.com/shisir2024/cureo_medi/blob/main/frontend/consultation.html): static page · `frontend/consultation.html`
- [Consultation client](https://github.com/shisir2024/cureo_medi/blob/main/frontend/consultation.js): browser JavaScript · `frontend/consultation.js`
- [Doctor portal client](https://github.com/shisir2024/cureo_medi/blob/main/frontend/doctor.js): browser JavaScript · `frontend/doctor.js`

### Backend boundary

- [Backend application](https://github.com/shisir2024/cureo_medi/blob/main/backend/main.py): Python API app · Initializes domain routers. · `backend/main.py`
- [Consultation routes](https://github.com/shisir2024/cureo_medi/blob/main/backend/routers/consult_routes.py): HTTP router · `backend/routers/consult_routes.py`
- [Authentication routes](https://github.com/shisir2024/cureo_medi/blob/main/backend/routers/auth_routes.py): HTTP router · `backend/routers/auth_routes.py`
- [WebSocket manager](https://github.com/shisir2024/cureo_medi/blob/main/backend/ws_manager.py): connection state · `backend/ws_manager.py`

### Clinical pipeline

- [Agent orchestrator](https://github.com/shisir2024/cureo_medi/blob/main/backend/orchestrator.py): control flow · Coordinates triage, selective specialist analysis, and response assembly. · `backend/orchestrator.py`
- [Safety triage](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/triage.py): agent · First decision stage for safety-sensitive branching. · `backend/agents/triage.py`
- [Symptom analysis](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/symptom_analyzer.py): agent · `backend/agents/symptom_analyzer.py`
- [Diagnosis agent](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/diagnosis.py): specialist agent · `backend/agents/diagnosis.py`
- [Treatment agent](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/treatment.py): specialist agent · `backend/agents/treatment.py`
- [Health scoring](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/health_score.py): specialist agent · `backend/agents/health_score.py`
- [Report compiler](https://github.com/shisir2024/cureo_medi/blob/main/backend/agents/report.py): response aggregation · Produces the structured JSON response contract. · `backend/agents/report.py`

### Platform services

- [Identity service](https://github.com/shisir2024/cureo_medi/blob/main/backend/auth.py): authentication · `backend/auth.py`
- [Persistence](https://github.com/shisir2024/cureo_medi/blob/main/backend/database.py): database access · Centralized access for consultation-related records. · `backend/database.py`
- [LLM integration](https://github.com/shisir2024/cureo_medi/blob/main/backend/llm.py): provider gateway · Centralizes model and API-key access. · `backend/llm.py`
- [Safety prompt](https://github.com/shisir2024/cureo_medi/blob/main/backend/system_prompt.py): shared prompt · Provides global safety framing. · `backend/system_prompt.py`
- [Process deployment](https://github.com/shisir2024/cureo_medi/blob/main/Procfile): deployment entrypoint · `Procfile`
- [Local startup](https://github.com/shisir2024/cureo_medi/blob/main/run.sh): startup script · `run.sh`

## Connections

- Consultation UI → Consultation client: loads
- Consultation client → Consultation routes: HTTP
- Doctor portal client → Backend application: doctor APIs
- Backend application → Consultation routes: mounts
- Backend application → Authentication routes: mounts
- Backend application → WebSocket manager: real-time state
- Authentication routes → Identity service: authenticates
- Identity service → Persistence: user records
- Consultation routes → Agent orchestrator: consultation request
- Consultation routes → Persistence: consultation records
- Agent orchestrator → Safety triage: first stage
- Safety triage → Symptom analysis: analyze or emergency path
- Symptom analysis → Diagnosis agent: routine analysis
- Symptom analysis → Treatment agent: routine analysis
- Symptom analysis → Health scoring: scoring
- Safety triage → Report compiler: emergency fallback
- Diagnosis agent → Report compiler: findings
- Treatment agent → Report compiler: guidance
- Health scoring → Report compiler: score
- Report compiler → Consultation routes: structured JSON
- Agent orchestrator → LLM integration: model access
- Safety triage → Safety prompt: safety framing
- Process deployment → Backend application: runs
- Local startup → Backend application: starts