# halmosil/voxellabel architecture

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

## Overview

CT Annotation Platform manages DICOM imaging and clinical records organized into cases and studies, then supports annotation, review, and study workflows. The main path is browser upload/import → asynchronous ingestion and de-identification → object storage and metadata → browsing and annotation → workflow review. Admin capabilities also cover memberships, clinical data, analytics, and reusable workflow templates. The README documents the end-to-end service path; some subsystem links below are based on its documented roles and the repository tree rather than sampled implementation.

Main entry points: [`admin-ui/src/App.tsx`](https://github.com/halmosil/voxellabel/blob/master/admin-ui/src/App.tsx) (Admin console), [`libs/shared-models/shared_models/database.py`](https://github.com/halmosil/voxellabel/blob/master/libs/shared-models/shared_models/database.py) (Platform database), [`services/ingestion-service/app/pipeline.py`](https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/pipeline.py) (DICOM pipeline), [`services/data-service/app/api/routes.py`](https://github.com/halmosil/voxellabel/blob/master/services/data-service/app/api/routes.py) (Data API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User applications"]
  node_adminui["Admin console<br/>[App.tsx]"]
  node_annotatorui["CT viewer<br/>[ViewerPage.tsx]"]
  node_desktop["Clinician desktop<br/>[main.js]"]
end

subgraph group_ingestion["DICOM ingestion"]
  node_ingestapi["Upload API<br/>[routes.py]"]
  node_ingesttasks["Async jobs<br/>[tasks.py]"]
  node_pipeline["DICOM pipeline<br/>[pipeline.py]"]
  node_deid["De-identification<br/>[deidentify.py]"]
end

subgraph group_core["Platform services"]
  node_dataapi["Data API<br/>[routes.py]"]
  node_adminapi["Admin API<br/>[main.py]"]
  node_models["Shared data model<br/>[models.py]"]
  node_database[("Platform database<br/>[database.py]")]
  node_objects[("Object storage")]
  node_analytics["Study analytics<br/>[api.py]"]
  node_usage["Usage insights<br/>[api.py]"]
end

subgraph group_annotation["Annotation and review"]
  node_annotationapi["Annotation API<br/>[routes.py]"]
  node_maskstore["Annotation masks<br/>[storage.py]"]
end

subgraph group_workflow["Study workflows"]
  node_workflowapi["Workflow API<br/>[routes.py]"]
  node_engine["Workflow run engine<br/>[engine.py]"]
  node_templates["Pipeline templates"]
end

node_user(("Clinician / admin"))
node_auth["Keycloak"]
node_redis["Job broker"]
node_ollama["Ollama model"]
node_mcp["MCP tools<br/>[server.py]"]

node_user -->|"uses"| node_adminui
node_user -->|"annotates"| node_annotatorui
node_user -.->|"uses"| node_desktop
node_adminui -->|"uploads"| node_ingestapi
node_ingestapi -->|"queues jobs"| node_ingesttasks
node_ingesttasks -->|"dispatches"| node_redis
node_ingesttasks -->|"runs"| node_pipeline
node_pipeline -->|"de-identifies"| node_deid
node_pipeline -->|"stores DICOM"| node_objects
node_pipeline -->|"persists metadata"| node_database
node_adminui -->|"browses data"| node_dataapi
node_dataapi -->|"reads records"| node_database
node_dataapi -->|"reads files"| node_objects
node_dataapi -->|"provides data links"| node_annotatorui
node_annotatorui -->|"submits work"| node_annotationapi
node_annotationapi -->|"reads and writes"| node_database
node_annotationapi -->|"stores masks"| node_maskstore
node_maskstore -->|"writes masks"| node_objects
node_adminui -->|"administers studies"| node_adminapi
node_adminapi -->|"manages records"| node_database
node_adminapi -->|"accesses files"| node_objects
node_adminui -->|"edits workflows"| node_workflowapi
node_workflowapi -->|"runs cards"| node_engine
node_engine -->|"reads and updates"| node_database
node_adminui -->|"manages templates"| node_templates
node_templates -->|"persists templates"| node_database
node_adminui -->|"views study metrics"| node_analytics
node_analytics -->|"queries study data"| node_database
node_adminui -->|"views usage"| node_usage
node_usage -->|"queries usage data"| node_database
node_adminui -->|"authenticates"| node_auth
node_annotatorui -->|"authenticates"| node_auth
node_workflowapi -.->|"requests chat"| node_ollama
node_workflowapi -.->|"uses tools via"| node_mcp

click node_adminui "https://github.com/halmosil/voxellabel/blob/master/admin-ui/src/App.tsx"
click node_annotatorui "https://github.com/halmosil/voxellabel/blob/master/ct-annotator/frontend/src/pages/ViewerPage.tsx"
click node_desktop "https://github.com/halmosil/voxellabel/blob/master/clinician-app/main.js"
click node_ingestapi "https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/api/routes.py"
click node_ingesttasks "https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/tasks.py"
click node_pipeline "https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/pipeline.py"
click node_deid "https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/deidentify.py"
click node_dataapi "https://github.com/halmosil/voxellabel/blob/master/services/data-service/app/api/routes.py"
click node_adminapi "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/main.py"
click node_annotationapi "https://github.com/halmosil/voxellabel/blob/master/services/annotation-service/app/api/routes.py"
click node_maskstore "https://github.com/halmosil/voxellabel/blob/master/ct-annotator/backend/app/storage.py"
click node_models "https://github.com/halmosil/voxellabel/blob/master/libs/shared-models/shared_models/models.py"
click node_database "https://github.com/halmosil/voxellabel/blob/master/libs/shared-models/shared_models/database.py"
click node_workflowapi "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/workflow/routes.py"
click node_engine "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/workflow/engine.py"
click node_templates "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/pipeline_templates.py"
click node_analytics "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/study_analytics/api.py"
click node_usage "https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/usage/api.py"
click node_mcp "https://github.com/halmosil/voxellabel/blob/master/services/mcp-server/app/server.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_adminui,node_annotatorui,node_desktop toneBlue
class node_ingestapi,node_ingesttasks,node_pipeline,node_deid toneAmber
class node_dataapi,node_adminapi,node_models,node_database,node_objects,node_analytics,node_usage toneMint
class node_annotationapi,node_maskstore toneRose
class node_workflowapi,node_engine,node_templates,node_user,node_auth,node_redis,node_ollama toneIndigo
class node_mcp toneTeal
```

## Components

### User applications

- [Admin console](https://github.com/halmosil/voxellabel/blob/master/admin-ui/src/App.tsx): `admin-ui/src/App.tsx`
- [CT viewer](https://github.com/halmosil/voxellabel/blob/master/ct-annotator/frontend/src/pages/ViewerPage.tsx): `ct-annotator/frontend/src/pages/ViewerPage.tsx`
- [Clinician desktop](https://github.com/halmosil/voxellabel/blob/master/clinician-app/main.js): `clinician-app/main.js`

### DICOM ingestion

- [Upload API](https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/api/routes.py): `services/ingestion-service/app/api/routes.py`
- [Async jobs](https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/tasks.py): `services/ingestion-service/app/tasks.py`
- [DICOM pipeline](https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/pipeline.py): `services/ingestion-service/app/pipeline.py`
- [De-identification](https://github.com/halmosil/voxellabel/blob/master/services/ingestion-service/app/deidentify.py): `services/ingestion-service/app/deidentify.py`

### Platform services

- [Data API](https://github.com/halmosil/voxellabel/blob/master/services/data-service/app/api/routes.py): `services/data-service/app/api/routes.py`
- [Admin API](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/main.py): `services/admin-service/app/main.py`
- [Shared data model](https://github.com/halmosil/voxellabel/blob/master/libs/shared-models/shared_models/models.py): `libs/shared-models/shared_models/models.py`
- [Platform database](https://github.com/halmosil/voxellabel/blob/master/libs/shared-models/shared_models/database.py): `libs/shared-models/shared_models/database.py`
- **Object storage**
- [Study analytics](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/study_analytics/api.py): `services/admin-service/app/study_analytics/api.py`
- [Usage insights](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/usage/api.py): `services/admin-service/app/usage/api.py`

### Annotation and review

- [Annotation API](https://github.com/halmosil/voxellabel/blob/master/services/annotation-service/app/api/routes.py): `services/annotation-service/app/api/routes.py`
- [Annotation masks](https://github.com/halmosil/voxellabel/blob/master/ct-annotator/backend/app/storage.py): `ct-annotator/backend/app/storage.py`

### Study workflows

- [Workflow API](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/workflow/routes.py): `services/admin-service/app/api/workflow/routes.py`
- [Workflow run engine](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/workflow/engine.py): `services/admin-service/app/api/workflow/engine.py`
- [Pipeline templates](https://github.com/halmosil/voxellabel/blob/master/services/admin-service/app/api/pipeline_templates.py): `services/admin-service/app/api/pipeline_templates.py`

### Other components

- **Clinician / admin**
- **Keycloak**
- **Job broker**
- **Ollama model**
- [MCP tools](https://github.com/halmosil/voxellabel/blob/master/services/mcp-server/app/server.py): `services/mcp-server/app/server.py`

## Connections

- Clinician / admin → Admin console: uses
- Clinician / admin → CT viewer: annotates
- Clinician / admin → Clinician desktop: uses
- Admin console → Upload API: uploads
- Upload API → Async jobs: queues jobs
- Async jobs → Job broker: dispatches
- Async jobs → DICOM pipeline: runs
- DICOM pipeline → De-identification: de-identifies
- DICOM pipeline → Object storage: stores DICOM
- DICOM pipeline → Platform database: persists metadata
- Admin console → Data API: browses data
- Data API → Platform database: reads records
- Data API → Object storage: reads files
- Data API → CT viewer: provides data links
- CT viewer → Annotation API: submits work
- Annotation API → Platform database: reads and writes
- Annotation API → Annotation masks: stores masks
- Annotation masks → Object storage: writes masks
- Admin console → Admin API: administers studies
- Admin API → Platform database: manages records
- Admin API → Object storage: accesses files
- Admin console → Workflow API: edits workflows
- Workflow API → Workflow run engine: runs cards
- Workflow run engine → Platform database: reads and updates
- Admin console → Pipeline templates: manages templates
- Pipeline templates → Platform database: persists templates
- Admin console → Study analytics: views study metrics
- Study analytics → Platform database: queries study data
- Admin console → Usage insights: views usage
- Usage insights → Platform database: queries usage data
- Admin console → Keycloak: authenticates
- CT viewer → Keycloak: authenticates
- Workflow API → Ollama model: requests chat
- Workflow API → MCP tools: uses tools via