# ashrafabulsoud/siyadascribe architecture

> Architecture diagram of the GitHub repository ashrafabulsoud/siyadascribe, 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/ashrafabulsoud/siyadascribe
- Repository: https://github.com/ashrafabulsoud/siyadascribe

## Overview

SiyadaScribe is a local-first clinical scribe and patient-management application. Its main workflow takes a clinician’s consultation audio through transcription and template-based note generation, then supports reviewing and saving the encounter. Separate capabilities cover correspondence, patient tasks, document forms, and a knowledge-base assistant with optional MCP tools. The graph combines README-described product stages with paths in the tree; because most backend implementations were not sampled, some subsystem links are omitted rather than inferred.

Main entry points: [`server/server.py`](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/server.py) (FastAPI application), [`src/utils/api/patientApi.ts`](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/utils/api/patientApi.ts) (Frontend API clients), [`server/chat/engine.py`](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/chat/engine.py) (Tool orchestration), [`src/pages/PatientDetails.jsx`](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/PatientDetails.jsx) (Patient encounter UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop and UI"]
  node_desktop["Desktop shell<br/>[main.rs]"]
  node_routes["App routes<br/>[AppRoutes.jsx]"]
  node_api_client["Frontend API clients<br/>[patientApi.ts]"]
end

subgraph group_clinical["Clinical workflows"]
  node_patient_ui["Patient encounter UI<br/>[PatientDetails.jsx]"]
  node_transcribe_ui["Transcription UI"]
  node_transcription["Audio transcription<br/>[audio.py]"]
  node_note_processing["Template note generation<br/>[summarisation.py]"]
  node_refinement["Adaptive refinement"]
  node_letter_ui["Correspondence editor<br/>[LetterPanel.jsx]"]
  node_jobs_ui["Outstanding tasks"]
  node_pdf_ui["PDF form tools"]
end

subgraph group_assistant["AI and knowledge"]
  node_chat_ui["Assistant chat<br/>[ChatPanel.jsx]"]
  node_chat_engine["Tool orchestration<br/>[engine.py]"]
  node_rag_ui["Knowledge base UI<br/>[Rag.jsx]"]
  node_rag_retrieval["Vector retrieval<br/>[vector_store.py]"]
end

subgraph group_backend["Backend services"]
  node_note_api["Patient API<br/>[patient.py]"]
  node_letter_api["Letter generation API<br/>[letter.py]"]
  node_jobs_api["Task management API<br/>[dashboard.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_rag_api["Knowledge base API<br/>[rag.py]"]
  node_pdf_api["PDF forms API<br/>[pdf_forms.py]"]
  node_server["FastAPI application<br/>[server.py]"]
end

subgraph group_state["Data and models"]
  node_pdf_store[("PDF template storage<br/>[storage.py]")]
  node_repositories[("Clinical repositories<br/>[patient.py]")]
  node_config[("Configuration manager<br/>[manager.py]")]
end

node_clinician(("Clinician"))
node_llm["LLM provider"]
node_transcription_service["Transcription provider"]
node_mcp["MCP tool servers"]

node_clinician -->|"uses"| node_desktop
node_desktop -->|"hosts"| node_routes
node_routes -->|"opens encounter"| node_patient_ui
node_patient_ui -->|"captures consultation"| node_transcribe_ui
node_transcribe_ui -->|"requests transcription"| node_api_client
node_api_client -->|"sends API request"| node_server
node_server -->|"routes transcription"| node_transcription
node_transcription -.->|"sends audio"| node_transcription_service
node_patient_ui -->|"saves encounter"| node_api_client
node_server -->|"routes patient API"| node_note_api
node_note_api -->|"generates note"| node_note_processing
node_note_processing -.->|"requests summary"| node_llm
node_note_processing -->|"refines output"| node_refinement
node_note_api -->|"reads and writes"| node_repositories
node_letter_ui -->|"requests correspondence"| node_api_client
node_server -->|"routes letter API"| node_letter_api
node_letter_api -->|"reads encounter"| node_repositories
node_jobs_ui -->|"loads tasks"| node_api_client
node_server -->|"routes dashboard API"| node_jobs_api
node_jobs_api -->|"reads task data"| node_repositories
node_chat_ui -->|"sends chat"| node_api_client
node_server -->|"routes chat API"| node_chat_api
node_chat_api -->|"dispatches request"| node_chat_engine
node_chat_engine -.->|"requests response"| node_llm
node_chat_engine -->|"invokes search tools"| node_rag_retrieval
node_chat_engine -.->|"invokes tools"| node_mcp
node_rag_ui -->|"manages documents"| node_api_client
node_server -->|"routes RAG API"| node_rag_api
node_rag_api -->|"manages retrieval"| node_rag_retrieval
node_rag_retrieval -.->|"requests embeddings"| node_llm
node_pdf_ui -->|"manages forms"| node_api_client
node_server -->|"routes forms API"| node_pdf_api
node_pdf_api -->|"reads and writes templates"| node_pdf_store
node_server -->|"loads configuration"| node_config

click node_desktop "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src-tauri/src/main.rs"
click node_routes "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/layout/AppRoutes.jsx"
click node_patient_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/PatientDetails.jsx"
click node_transcribe_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/transcription/TranscriptionPanel.jsx"
click node_transcription "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/transcription/audio.py"
click node_note_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/patient.py"
click node_note_processing "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/nlp_tools/summarisation.py"
click node_refinement "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/nlp_tools/adaptive_refinement.py"
click node_letter_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/letter/LetterPanel.jsx"
click node_letter_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/letter.py"
click node_jobs_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/OutstandingJobs.jsx"
click node_jobs_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/dashboard.py"
click node_chat_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/chat/ChatPanel.jsx"
click node_chat_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/chat.py"
click node_chat_engine "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/chat/engine.py"
click node_rag_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/Rag.jsx"
click node_rag_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/rag.py"
click node_rag_retrieval "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/rag/vector_store.py"
click node_pdf_ui "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/pdf-forms/FormTemplatesPanel.jsx"
click node_pdf_api "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/pdf_forms.py"
click node_pdf_store "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/pdf_forms/storage.py"
click node_api_client "https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/utils/api/patientApi.ts"
click node_server "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/server.py"
click node_repositories "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/database/repositories/patient.py"
click node_config "https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/database/config/manager.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_desktop,node_routes,node_api_client toneBlue
class node_patient_ui,node_transcribe_ui,node_transcription,node_note_processing,node_refinement,node_letter_ui,node_jobs_ui,node_pdf_ui toneAmber
class node_chat_ui,node_chat_engine,node_rag_ui,node_rag_retrieval,node_mcp toneMint
class node_note_api,node_letter_api,node_jobs_api,node_chat_api,node_rag_api,node_pdf_api,node_server toneRose
class node_pdf_store,node_repositories,node_config,node_clinician,node_llm,node_transcription_service toneIndigo
```

## Components

### Desktop and UI

- [Desktop shell](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src-tauri/src/main.rs): `src-tauri/src/main.rs`
- [App routes](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/layout/AppRoutes.jsx): `src/components/layout/AppRoutes.jsx`
- [Frontend API clients](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/utils/api/patientApi.ts): `src/utils/api/patientApi.ts`

### Clinical workflows

- [Patient encounter UI](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/PatientDetails.jsx): `src/pages/PatientDetails.jsx`
- [Transcription UI](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/transcription/TranscriptionPanel.jsx): `src/components/panels/transcription/TranscriptionPanel.jsx`
- [Audio transcription](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/transcription/audio.py): `server/transcription/audio.py`
- [Template note generation](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/nlp_tools/summarisation.py): `server/nlp_tools/summarisation.py`
- [Adaptive refinement](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/nlp_tools/adaptive_refinement.py): `server/nlp_tools/adaptive_refinement.py`
- [Correspondence editor](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/letter/LetterPanel.jsx): `src/components/panels/letter/LetterPanel.jsx`
- [Outstanding tasks](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/OutstandingJobs.jsx): `src/pages/OutstandingJobs.jsx`
- [PDF form tools](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/pdf-forms/FormTemplatesPanel.jsx): `src/components/pdf-forms/FormTemplatesPanel.jsx`

### AI and knowledge

- [Assistant chat](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/components/panels/chat/ChatPanel.jsx): `src/components/panels/chat/ChatPanel.jsx`
- [Tool orchestration](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/chat/engine.py): `server/chat/engine.py`
- [Knowledge base UI](https://github.com/ashrafabulsoud/siyadascribe/blob/main/src/pages/Rag.jsx): `src/pages/Rag.jsx`
- [Vector retrieval](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/rag/vector_store.py): `server/rag/vector_store.py`

### Backend services

- [Patient API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/patient.py): `server/api/patient.py`
- [Letter generation API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/letter.py): `server/api/letter.py`
- [Task management API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/dashboard.py): `server/api/dashboard.py`
- [Chat API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/chat.py): `server/api/chat.py`
- [Knowledge base API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/rag.py): `server/api/rag.py`
- [PDF forms API](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/api/pdf_forms.py): `server/api/pdf_forms.py`
- [FastAPI application](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/server.py): `server/server.py`

### Data and models

- [PDF template storage](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/pdf_forms/storage.py): `server/pdf_forms/storage.py`
- [Clinical repositories](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/database/repositories/patient.py): `server/database/repositories/patient.py`
- [Configuration manager](https://github.com/ashrafabulsoud/siyadascribe/blob/main/server/database/config/manager.py): `server/database/config/manager.py`

### Other components

- **Clinician**
- **LLM provider**
- **Transcription provider**
- **MCP tool servers**

## Connections

- Clinician → Desktop shell: uses
- Desktop shell → App routes: hosts
- App routes → Patient encounter UI: opens encounter
- Patient encounter UI → Transcription UI: captures consultation
- Transcription UI → Frontend API clients: requests transcription
- Frontend API clients → FastAPI application: sends API request
- FastAPI application → Audio transcription: routes transcription
- Audio transcription → Transcription provider: sends audio
- Patient encounter UI → Frontend API clients: saves encounter
- FastAPI application → Patient API: routes patient API
- Patient API → Template note generation: generates note
- Template note generation → LLM provider: requests summary
- Template note generation → Adaptive refinement: refines output
- Patient API → Clinical repositories: reads and writes
- Correspondence editor → Frontend API clients: requests correspondence
- FastAPI application → Letter generation API: routes letter API
- Letter generation API → Clinical repositories: reads encounter
- Outstanding tasks → Frontend API clients: loads tasks
- FastAPI application → Task management API: routes dashboard API
- Task management API → Clinical repositories: reads task data
- Assistant chat → Frontend API clients: sends chat
- FastAPI application → Chat API: routes chat API
- Chat API → Tool orchestration: dispatches request
- Tool orchestration → LLM provider: requests response
- Tool orchestration → Vector retrieval: invokes search tools
- Tool orchestration → MCP tool servers: invokes tools
- Knowledge base UI → Frontend API clients: manages documents
- FastAPI application → Knowledge base API: routes RAG API
- Knowledge base API → Vector retrieval: manages retrieval
- Vector retrieval → LLM provider: requests embeddings
- PDF form tools → Frontend API clients: manages forms
- FastAPI application → PDF forms API: routes forms API
- PDF forms API → PDF template storage: reads and writes templates
- FastAPI application → Configuration manager: loads configuration