# xaltezzarx/boneqc architecture

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

- Interactive diagram: https://gitdiagram.com/xaltezzarx/boneqc
- Repository: https://github.com/xaltezzarx/boneqc

## Overview

BoneQC is a web platform for technical quality control of DXA DICOM studies, not a diagnostic system. The main workflow is study upload and validation, queued analysis, frozen C7 inference, and a structured QC result for review. The API also supports expert annotations and consensus, dataset snapshots, model management, audit, and operations. The README documents the end-to-end architecture; source-index references and excerpts clarify several API, queue, and evaluation responsibilities. Worker internals and some route implementations were not excerpted, so their detailed relationships are shown only where documented or indexed.

Main entry points: [`apps/api/app/worker.py`](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/worker.py) (Processing worker), [`apps/api/app/main.py`](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/main.py) (API router), [`apps/web/app/(protected)/studies/[id]/page.tsx`](https://github.com/xaltezzarx/boneqc/blob/main/apps/web/app/(protected)/studies/%5Bid%5D/page.tsx) (Web workspace), [`apps/api/app/api/v1/studies.py`](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/studies.py) (Study and dataset routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web workspace<br/>[page.tsx]"]
  node_review["Expert review"]
  node_api_proxy["Web API proxy<br/>[route.ts]"]
end

subgraph group_api["Product API"]
  node_api_app["API router<br/>[main.py]"]
  node_study_routes["Study and dataset routes<br/>[studies.py]"]
  node_analysis_routes["Analysis routes<br/>[analysis.py]"]
  node_expert_routes["Annotation routes<br/>[annotations.py]"]
end

subgraph group_analysis["QC processing"]
  node_analysis_service["Job creation<br/>[service.py]"]
  node_worker["Processing worker<br/>[worker.py]"]
  node_dicom["DICOM safeguards"]
  node_quality["Quality evaluation<br/>[engine.py]"]
  node_uncertainty["Uncertainty evaluation<br/>[engine.py]"]
  node_decision["Decision resolution<br/>[resolver.py]"]
end

subgraph group_state["Product state"]
  node_results[("Analysis results<br/>[analysis_result.py]")]
  node_audit[("Audit events<br/>[service.py]")]
  node_storage[("Study object storage<br/>[service.py]")]
  node_queue["Analysis queue<br/>[service.py]"]
  node_model_registry[("Model registry<br/>[service.py]")]
  node_annotations[("Expert annotations")]
  node_snapshots[("Dataset snapshots<br/>[snapshots.py]")]
end

subgraph group_runtime["Inference runtimes"]
  node_c7_adapter["C7 product adapter<br/>[c7_product.py]"]
  node_c7_gateway["C7 gateway client<br/>[c7_gateway.py]"]
  node_c7_runtime["Frozen C7 runtime"]
  node_ai_engine["Product AI service<br/>[main.py]"]
end

node_user(("Clinical user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"requests"| node_api_proxy
node_api_proxy -->|"forwards requests"| node_api_app
node_api_app -->|"registers routes"| node_study_routes
node_api_app -->|"registers routes"| node_analysis_routes
node_api_app -->|"registers routes"| node_expert_routes
node_study_routes -.->|"stores study files"| node_storage
node_analysis_routes -.->|"creates jobs"| node_analysis_service
node_analysis_service -->|"enqueues job"| node_queue
node_analysis_service -->|"records event"| node_audit
node_queue -->|"dispatches jobs"| node_worker
node_worker -->|"checks DICOM"| node_dicom
node_worker -->|"invokes analysis"| node_c7_adapter
node_c7_adapter -->|"uses gateway"| node_c7_gateway
node_c7_gateway -->|"calls runtime"| node_c7_runtime
node_worker -->|"evaluates observations"| node_quality
node_worker -->|"evaluates confidence"| node_uncertainty
node_worker -->|"resolves outcome"| node_decision
node_worker -->|"persists result"| node_results
node_results -->|"presents result"| node_webapp
node_webapp -->|"opens review"| node_review
node_review -.->|"submits annotations"| node_expert_routes
node_expert_routes -.->|"records consensus"| node_annotations
node_study_routes -.->|"manages snapshots"| node_snapshots
node_worker -->|"resolves model"| node_model_registry
node_worker -.->|"optional remote inference"| node_ai_engine

click node_webapp "https://github.com/xaltezzarx/boneqc/blob/main/apps/web/app/(protected)/studies/%5Bid%5D/page.tsx"
click node_review "https://github.com/xaltezzarx/boneqc/blob/main/apps/web/components/clinical-review-panel.tsx"
click node_api_proxy "https://github.com/xaltezzarx/boneqc/blob/main/apps/web/app/api/backend/%5B...path%5D/route.ts"
click node_api_app "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/main.py"
click node_study_routes "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/studies.py"
click node_analysis_routes "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/analysis.py"
click node_expert_routes "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/annotations.py"
click node_analysis_service "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/analysis/service.py"
click node_worker "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/worker.py"
click node_dicom "https://github.com/xaltezzarx/boneqc/tree/main/apps/api/app/dicom"
click node_quality "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/quality/engine.py"
click node_uncertainty "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/uncertainty/engine.py"
click node_decision "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/decision/resolver.py"
click node_results "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/models/analysis_result.py"
click node_audit "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/audit/service.py"
click node_storage "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/storage/service.py"
click node_queue "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/queue/service.py"
click node_model_registry "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/model_registry/service.py"
click node_c7_adapter "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/ai/c7_product.py"
click node_c7_gateway "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/ai/c7_gateway.py"
click node_ai_engine "https://github.com/xaltezzarx/boneqc/blob/main/apps/ai-engine/app/main.py"
click node_annotations "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/models/study_annotation_consensus.py"
click node_snapshots "https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/dataset/snapshots.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_webapp,node_review,node_api_proxy,node_user toneBlue
class node_api_app,node_study_routes,node_analysis_routes,node_expert_routes toneAmber
class node_analysis_service,node_worker,node_dicom,node_quality,node_uncertainty,node_decision toneMint
class node_results,node_audit,node_storage,node_queue,node_model_registry,node_annotations,node_snapshots toneRose
class node_c7_adapter,node_c7_gateway,node_c7_runtime,node_ai_engine toneIndigo
```

## Components

### Web experience

- [Web workspace](https://github.com/xaltezzarx/boneqc/blob/main/apps/web/app/(protected)/studies/%5Bid%5D/page.tsx): `apps/web/app/(protected)/studies/[id]/page.tsx`
- [Expert review](https://github.com/xaltezzarx/boneqc/blob/main/apps/web/components/clinical-review-panel.tsx): `apps/web/components/clinical-review-panel.tsx`
- [Web API proxy](https://github.com/xaltezzarx/boneqc/blob/main/apps/web/app/api/backend/%5B...path%5D/route.ts): `apps/web/app/api/backend/[...path]/route.ts`

### Product API

- [API router](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Study and dataset routes](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/studies.py): `apps/api/app/api/v1/studies.py`
- [Analysis routes](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/analysis.py): `apps/api/app/api/v1/analysis.py`
- [Annotation routes](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/api/v1/annotations.py): `apps/api/app/api/v1/annotations.py`

### QC processing

- [Job creation](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/analysis/service.py): `apps/api/app/analysis/service.py`
- [Processing worker](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/worker.py): `apps/api/app/worker.py`
- [DICOM safeguards](https://github.com/xaltezzarx/boneqc/tree/main/apps/api/app/dicom): `apps/api/app/dicom`
- [Quality evaluation](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/quality/engine.py): `apps/api/app/quality/engine.py`
- [Uncertainty evaluation](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/uncertainty/engine.py): `apps/api/app/uncertainty/engine.py`
- [Decision resolution](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/decision/resolver.py): `apps/api/app/decision/resolver.py`

### Product state

- [Analysis results](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/models/analysis_result.py): `apps/api/app/models/analysis_result.py`
- [Audit events](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/audit/service.py): `apps/api/app/audit/service.py`
- [Study object storage](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/storage/service.py): `apps/api/app/storage/service.py`
- [Analysis queue](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/queue/service.py): `apps/api/app/queue/service.py`
- [Model registry](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/model_registry/service.py): `apps/api/app/model_registry/service.py`
- [Expert annotations](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/models/study_annotation_consensus.py): `apps/api/app/models/study_annotation_consensus.py`
- [Dataset snapshots](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/dataset/snapshots.py): `apps/api/app/dataset/snapshots.py`

### Inference runtimes

- [C7 product adapter](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/ai/c7_product.py): `apps/api/app/ai/c7_product.py`
- [C7 gateway client](https://github.com/xaltezzarx/boneqc/blob/main/apps/api/app/ai/c7_gateway.py): `apps/api/app/ai/c7_gateway.py`
- **Frozen C7 runtime**
- [Product AI service](https://github.com/xaltezzarx/boneqc/blob/main/apps/ai-engine/app/main.py): `apps/ai-engine/app/main.py`

### Other components

- **Clinical user**

## Connections

- Clinical user → Web workspace: uses (evidence: `README.md`)
- Web workspace → Web API proxy: requests (evidence: `apps/web/app/api/backend/[...path]/route.ts`)
- Web API proxy → API router: forwards requests (evidence: `README.md`)
- API router → Study and dataset routes: registers routes (evidence: `apps/api/app/main.py`)
- API router → Analysis routes: registers routes (evidence: `apps/api/app/main.py`)
- API router → Annotation routes: registers routes (evidence: `apps/api/app/main.py`)
- Study and dataset routes → Study object storage: stores study files
- Analysis routes → Job creation: creates jobs
- Job creation → Analysis queue: enqueues job (evidence: `apps/api/app/analysis/service.py`)
- Job creation → Audit events: records event (evidence: `apps/api/app/analysis/service.py`)
- Analysis queue → Processing worker: dispatches jobs (evidence: `README.md`)
- Processing worker → DICOM safeguards: checks DICOM (evidence: `apps/api/app/worker.py`)
- Processing worker → C7 product adapter: invokes analysis (evidence: `apps/api/app/worker.py`)
- C7 product adapter → C7 gateway client: uses gateway (evidence: `apps/api/app/ai/c7_product.py`)
- C7 gateway client → Frozen C7 runtime: calls runtime (evidence: `README.md`)
- Processing worker → Quality evaluation: evaluates observations (evidence: `apps/api/app/worker.py`)
- Processing worker → Uncertainty evaluation: evaluates confidence (evidence: `apps/api/app/worker.py`)
- Processing worker → Decision resolution: resolves outcome (evidence: `apps/api/app/worker.py`)
- Processing worker → Analysis results: persists result (evidence: `README.md`)
- Analysis results → Web workspace: presents result (evidence: `README.md`)
- Web workspace → Expert review: opens review (evidence: `apps/web/components/clinical-review-panel.tsx`)
- Expert review → Annotation routes: submits annotations
- Annotation routes → Expert annotations: records consensus
- Study and dataset routes → Dataset snapshots: manages snapshots
- Processing worker → Model registry: resolves model (evidence: `apps/api/app/worker.py`)
- Processing worker → Product AI service: optional remote inference (evidence: `apps/api/app/worker.py`)
