# bloodworks-io/phlox architecture

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

- Interactive diagram: https://gitdiagram.com/bloodworks-io/phlox
- Repository: https://github.com/bloodworks-io/phlox

## Overview

Phlox is a local-first AI medical scribe and patient-management application. Its principal workflow is capturing a consultation, transcribing it, generating a template-structured clinical note, and saving it with patient records; users can then create correspondence and manage follow-up tasks. The product also includes an agent with literature, knowledge-base, and optional MCP tools, plus document/form processing and configurable models. The graph reflects documented capabilities and sampled orchestration; several backend route-to-service connections are not shown because their implementations were not sampled.

Main entry points: [`src/components/layout/AppRoutes.jsx`](https://github.com/bloodworks-io/phlox/blob/main/src/components/layout/AppRoutes.jsx) (Application routes), [`server/api/patient.py`](https://github.com/bloodworks-io/phlox/blob/main/server/api/patient.py) (Patient API), [`server/chat/engine.py`](https://github.com/bloodworks-io/phlox/blob/main/server/chat/engine.py) (Agent orchestration), [`src/App.jsx`](https://github.com/bloodworks-io/phlox/blob/main/src/App.jsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop and UI"]
  node_ui["React application<br/>[App.jsx]"]
  node_routes["Application routes<br/>[AppRoutes.jsx]"]
  node_tauri["Desktop runtime<br/>[main.rs]"]
end

subgraph group_api["Application API"]
  node_server["FastAPI server<br/>[server.py]"]
  node_patient_api["Patient API<br/>[patient.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_rag_api["Knowledge API<br/>[rag.py]"]
  node_transcribe_api["Transcription API<br/>[transcribe.py]"]
  node_letter_api["Letter API<br/>[letter.py]"]
  node_form_api["PDF forms API<br/>[pdf_forms.py]"]
end

subgraph group_clinical["Clinical workflows"]
  node_transcription["Audio transcription<br/>[audio.py]"]
  node_note_generation["Structured note generation<br/>[summarisation.py]"]
  node_letters["Correspondence generation<br/>[letter.py]"]
  node_tasks["Clinical tasks<br/>[jobs.py]"]
  node_forms["PDF form processing<br/>[storage.py]"]
end

subgraph group_ai["AI and knowledge"]
  node_chat_engine["Agent orchestration<br/>[engine.py]"]
  node_tools["Agent tools<br/>[registry.py]"]
  node_rag["Retrieval and vectors<br/>[vector_store.py]"]
  node_llm["LLM client<br/>[client.py]"]
  node_mcp["MCP client<br/>[client.py]"]
end

subgraph group_data["Persistence"]
  node_records[("Clinical repositories<br/>[patient.py]")]
  node_config[("User configuration<br/>[manager.py]")]
  node_docs_db[("Documents database<br/>[documents_db.py]")]
end

node_clinician(("Clinician"))
node_transcription_service["Whisper-compatible service"]
node_llm_service["OpenAI-compatible LLM"]
node_mcp_service["External MCP servers"]

node_clinician -->|"uses"| node_ui
node_ui -->|"renders"| node_routes
node_ui -.->|"desktop runtime"| node_tauri
node_routes -->|"patient requests"| node_patient_api
node_routes -->|"chat requests"| node_chat_api
node_routes -->|"knowledge requests"| node_rag_api
node_routes -->|"transcription requests"| node_transcribe_api
node_routes -->|"letter requests"| node_letter_api
node_routes -->|"form requests"| node_form_api
node_server -->|"mounts routes"| node_patient_api
node_transcribe_api -->|"handles transcription"| node_transcription
node_transcription -.->|"sends audio"| node_transcription_service
node_patient_api -->|"generates notes"| node_note_generation
node_note_generation -->|"requests generation"| node_llm
node_letter_api -->|"generates letters"| node_letters
node_chat_api -->|"orchestrates chat"| node_chat_engine
node_chat_engine -->|"requests responses"| node_llm
node_chat_engine -->|"dispatches tools"| node_tools
node_tools -->|"retrieves knowledge"| node_rag
node_tools -.->|"invokes MCP tools"| node_mcp
node_mcp -.->|"dispatches calls"| node_mcp_service
node_llm -.->|"sends prompts"| node_llm_service
node_patient_api -->|"stores patient data"| node_records
node_letter_api -->|"stores correspondence"| node_records
node_patient_api -->|"manages jobs"| node_tasks
node_rag_api -->|"manages knowledge"| node_rag
node_form_api -->|"manages templates"| node_forms
node_forms -->|"stores templates"| node_docs_db
node_chat_engine -->|"reads prompts"| node_config
node_note_generation -->|"uses templates"| node_config

click node_ui "https://github.com/bloodworks-io/phlox/blob/main/src/App.jsx"
click node_routes "https://github.com/bloodworks-io/phlox/blob/main/src/components/layout/AppRoutes.jsx"
click node_tauri "https://github.com/bloodworks-io/phlox/blob/main/src-tauri/src/main.rs"
click node_server "https://github.com/bloodworks-io/phlox/blob/main/server/server.py"
click node_patient_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/patient.py"
click node_chat_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/chat.py"
click node_rag_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/rag.py"
click node_transcribe_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/transcribe.py"
click node_letter_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/letter.py"
click node_form_api "https://github.com/bloodworks-io/phlox/blob/main/server/api/pdf_forms.py"
click node_transcription "https://github.com/bloodworks-io/phlox/blob/main/server/transcription/audio.py"
click node_note_generation "https://github.com/bloodworks-io/phlox/blob/main/server/nlp_tools/summarisation.py"
click node_letters "https://github.com/bloodworks-io/phlox/blob/main/server/nlp_tools/letter.py"
click node_tasks "https://github.com/bloodworks-io/phlox/blob/main/server/database/repositories/jobs.py"
click node_forms "https://github.com/bloodworks-io/phlox/blob/main/server/pdf_forms/storage.py"
click node_chat_engine "https://github.com/bloodworks-io/phlox/blob/main/server/chat/engine.py"
click node_tools "https://github.com/bloodworks-io/phlox/blob/main/server/chat/tools/registry.py"
click node_rag "https://github.com/bloodworks-io/phlox/blob/main/server/rag/vector_store.py"
click node_llm "https://github.com/bloodworks-io/phlox/blob/main/server/llm_client/client.py"
click node_mcp "https://github.com/bloodworks-io/phlox/blob/main/server/mcp/client.py"
click node_records "https://github.com/bloodworks-io/phlox/blob/main/server/database/repositories/patient.py"
click node_config "https://github.com/bloodworks-io/phlox/blob/main/server/database/config/manager.py"
click node_docs_db "https://github.com/bloodworks-io/phlox/blob/main/server/database/core/documents_db.py"

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_ui,node_routes,node_tauri toneBlue
class node_server,node_patient_api,node_chat_api,node_rag_api,node_transcribe_api,node_letter_api,node_form_api toneAmber
class node_transcription,node_note_generation,node_letters,node_tasks,node_forms,node_mcp_service toneMint
class node_chat_engine,node_tools,node_rag,node_llm,node_mcp toneRose
class node_records,node_config,node_docs_db,node_clinician,node_transcription_service,node_llm_service toneIndigo
```

## Components

### Desktop and UI

- [React application](https://github.com/bloodworks-io/phlox/blob/main/src/App.jsx): `src/App.jsx`
- [Application routes](https://github.com/bloodworks-io/phlox/blob/main/src/components/layout/AppRoutes.jsx): `src/components/layout/AppRoutes.jsx`
- [Desktop runtime](https://github.com/bloodworks-io/phlox/blob/main/src-tauri/src/main.rs): `src-tauri/src/main.rs`

### Application API

- [FastAPI server](https://github.com/bloodworks-io/phlox/blob/main/server/server.py): `server/server.py`
- [Patient API](https://github.com/bloodworks-io/phlox/blob/main/server/api/patient.py): `server/api/patient.py`
- [Chat API](https://github.com/bloodworks-io/phlox/blob/main/server/api/chat.py): `server/api/chat.py`
- [Knowledge API](https://github.com/bloodworks-io/phlox/blob/main/server/api/rag.py): `server/api/rag.py`
- [Transcription API](https://github.com/bloodworks-io/phlox/blob/main/server/api/transcribe.py): `server/api/transcribe.py`
- [Letter API](https://github.com/bloodworks-io/phlox/blob/main/server/api/letter.py): `server/api/letter.py`
- [PDF forms API](https://github.com/bloodworks-io/phlox/blob/main/server/api/pdf_forms.py): `server/api/pdf_forms.py`

### Clinical workflows

- [Audio transcription](https://github.com/bloodworks-io/phlox/blob/main/server/transcription/audio.py): `server/transcription/audio.py`
- [Structured note generation](https://github.com/bloodworks-io/phlox/blob/main/server/nlp_tools/summarisation.py): `server/nlp_tools/summarisation.py`
- [Correspondence generation](https://github.com/bloodworks-io/phlox/blob/main/server/nlp_tools/letter.py): `server/nlp_tools/letter.py`
- [Clinical tasks](https://github.com/bloodworks-io/phlox/blob/main/server/database/repositories/jobs.py): `server/database/repositories/jobs.py`
- [PDF form processing](https://github.com/bloodworks-io/phlox/blob/main/server/pdf_forms/storage.py): `server/pdf_forms/storage.py`

### AI and knowledge

- [Agent orchestration](https://github.com/bloodworks-io/phlox/blob/main/server/chat/engine.py): `server/chat/engine.py`
- [Agent tools](https://github.com/bloodworks-io/phlox/blob/main/server/chat/tools/registry.py): `server/chat/tools/registry.py`
- [Retrieval and vectors](https://github.com/bloodworks-io/phlox/blob/main/server/rag/vector_store.py): `server/rag/vector_store.py`
- [LLM client](https://github.com/bloodworks-io/phlox/blob/main/server/llm_client/client.py): `server/llm_client/client.py`
- [MCP client](https://github.com/bloodworks-io/phlox/blob/main/server/mcp/client.py): `server/mcp/client.py`

### Persistence

- [Clinical repositories](https://github.com/bloodworks-io/phlox/blob/main/server/database/repositories/patient.py): `server/database/repositories/patient.py`
- [User configuration](https://github.com/bloodworks-io/phlox/blob/main/server/database/config/manager.py): `server/database/config/manager.py`
- [Documents database](https://github.com/bloodworks-io/phlox/blob/main/server/database/core/documents_db.py): `server/database/core/documents_db.py`

### Other components

- **Clinician**
- **Whisper-compatible service**
- **OpenAI-compatible LLM**
- **External MCP servers**

## Connections

- Clinician → React application: uses
- React application → Application routes: renders
- React application → Desktop runtime: desktop runtime
- Application routes → Patient API: patient requests
- Application routes → Chat API: chat requests
- Application routes → Knowledge API: knowledge requests
- Application routes → Transcription API: transcription requests
- Application routes → Letter API: letter requests
- Application routes → PDF forms API: form requests
- FastAPI server → Patient API: mounts routes
- Transcription API → Audio transcription: handles transcription
- Audio transcription → Whisper-compatible service: sends audio
- Patient API → Structured note generation: generates notes
- Structured note generation → LLM client: requests generation
- Letter API → Correspondence generation: generates letters
- Chat API → Agent orchestration: orchestrates chat
- Agent orchestration → LLM client: requests responses
- Agent orchestration → Agent tools: dispatches tools
- Agent tools → Retrieval and vectors: retrieves knowledge
- Agent tools → MCP client: invokes MCP tools
- MCP client → External MCP servers: dispatches calls
- LLM client → OpenAI-compatible LLM: sends prompts
- Patient API → Clinical repositories: stores patient data
- Letter API → Clinical repositories: stores correspondence
- Patient API → Clinical tasks: manages jobs
- Knowledge API → Retrieval and vectors: manages knowledge
- PDF forms API → PDF form processing: manages templates
- PDF form processing → Documents database: stores templates
- Agent orchestration → User configuration: reads prompts
- Structured note generation → User configuration: uses templates