# technometer/lung-analysis-demo architecture

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

- Interactive diagram: https://gitdiagram.com/technometer/lung-analysis-demo
- Repository: https://github.com/technometer/lung-analysis-demo

## Overview

Lung Analysis Demo turns LUNA16 pulmonary nodule annotations into an interactive thoracic CT discovery experience. Its principal workflow cleans findings, derives clustering, anomaly scores and PCA coordinates, ingests enriched records into PostgreSQL, then serves spatial findings, cohort summaries and relational graphs to the browser. The frontend supports anatomical and PCA views, filtering, camera focus, finding inspection and study knowledge graphs. API route and UI capabilities are included from the README; their detailed implementations were not sampled.

Main entry points: [`frontend/js/main.js`](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/main.js) (3D scene and controls), [`src/database/connection.py`](https://github.com/technometer/lung-analysis-demo/blob/main/src/database/connection.py) (DB sessions), [`src/api/main.py`](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/main.py) (FastAPI application), [`src/api/routes/findings.py`](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/findings.py) (Spatial findings API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw["LUNA16 annotations<br/>[annotations.csv]"]
  node_clean["Cleaning pipeline<br/>[clean_pipeline.py]"]
  node_clean_csv["Clean findings<br/>[clean_findings.csv]"]
end

subgraph group_analysis["Finding analysis"]
  node_baseline["Unsupervised baseline<br/>[train_baseline.py]"]
  node_enriched_csv["Enriched findings"]
  node_model_artifacts["Fitted models"]
end

subgraph group_service["API and storage"]
  node_ingest["Relational ingestion<br/>[ingest_data.py]"]
  node_db_config["DB sessions<br/>[connection.py]"]
  node_orm["Study and finding models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_api["FastAPI application<br/>[main.py]"]
  node_schemas["API data contracts<br/>[schemas.py]"]
  node_finding_routes["Spatial findings API<br/>[findings.py]"]
  node_cluster_routes["Cohort summary API<br/>[clusters.py]"]
  node_graph_routes["Knowledge graph API<br/>[graph.py]"]
  node_health_routes["Health API<br/>[health.py]"]
end

subgraph group_ui["Interactive interface"]
  node_spa["Browser interface<br/>[index.html]"]
  node_main_ui["3D scene and controls<br/>[main.js]"]
  node_particles["Finding meshes<br/>[particles.js]"]
  node_hulls["Anatomical context<br/>[anatomicalHull.js]"]
  node_camera["Camera transitions<br/>[cameraManager.js]"]
  node_graph_ui["2D knowledge graph<br/>[knowledgeGraph.js]"]
end

node_analyst(("Clinical analyst"))

node_clean -->|"reads"| node_raw
node_clean -->|"writes"| node_clean_csv
node_baseline -->|"reads"| node_clean_csv
node_baseline -->|"writes"| node_enriched_csv
node_baseline -->|"saves"| node_model_artifacts
node_ingest -->|"reads"| node_enriched_csv
node_ingest -->|"uses sessions"| node_db_config
node_ingest -->|"creates records"| node_orm
node_ingest -->|"writes"| node_postgres
node_api -->|"registers"| node_finding_routes
node_api -->|"registers"| node_cluster_routes
node_api -->|"registers"| node_graph_routes
node_api -->|"registers"| node_health_routes
node_api -->|"serves"| node_spa
node_finding_routes -->|"gets sessions"| node_db_config
node_cluster_routes -->|"gets sessions"| node_db_config
node_graph_routes -->|"gets sessions"| node_db_config
node_health_routes -->|"gets sessions"| node_db_config
node_db_config -->|"connects"| node_postgres
node_finding_routes -->|"queries findings"| node_orm
node_cluster_routes -->|"aggregates findings"| node_orm
node_graph_routes -->|"queries studies and findings"| node_orm
node_health_routes -->|"checks connectivity"| node_postgres
node_finding_routes -->|"serializes response"| node_schemas
node_cluster_routes -->|"serializes response"| node_schemas
node_graph_routes -->|"serializes response"| node_schemas
node_analyst -->|"uses"| node_spa
node_spa -->|"loads"| node_main_ui
node_main_ui -->|"requests spatial findings"| node_finding_routes
node_main_ui -->|"requests cohort metrics"| node_cluster_routes
node_main_ui -->|"creates finding meshes"| node_particles
node_main_ui -->|"creates anatomy"| node_hulls
node_main_ui -->|"focuses camera"| node_camera
node_main_ui -->|"opens graph"| node_graph_ui
node_graph_ui -->|"requests study graph"| node_graph_routes

click node_raw "https://github.com/technometer/lung-analysis-demo/blob/main/data/raw/annotations.csv"
click node_clean "https://github.com/technometer/lung-analysis-demo/blob/main/src/data/clean_pipeline.py"
click node_clean_csv "https://github.com/technometer/lung-analysis-demo/blob/main/data/processed/clean_findings.csv"
click node_baseline "https://github.com/technometer/lung-analysis-demo/blob/main/src/models/train_baseline.py"
click node_enriched_csv "https://github.com/technometer/lung-analysis-demo/blob/main/data/processed/enriched_findings.csv"
click node_model_artifacts "https://github.com/technometer/lung-analysis-demo/tree/main/models"
click node_ingest "https://github.com/technometer/lung-analysis-demo/blob/main/src/database/ingest_data.py"
click node_db_config "https://github.com/technometer/lung-analysis-demo/blob/main/src/database/connection.py"
click node_orm "https://github.com/technometer/lung-analysis-demo/blob/main/src/database/models.py"
click node_api "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/main.py"
click node_schemas "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/schemas.py"
click node_finding_routes "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/findings.py"
click node_cluster_routes "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/clusters.py"
click node_graph_routes "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/graph.py"
click node_health_routes "https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/health.py"
click node_spa "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/index.html"
click node_main_ui "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/main.js"
click node_particles "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/particles.js"
click node_hulls "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/anatomicalHull.js"
click node_camera "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/cameraManager.js"
click node_graph_ui "https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/knowledgeGraph.js"

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_raw,node_clean,node_clean_csv toneBlue
class node_baseline,node_enriched_csv,node_model_artifacts toneAmber
class node_ingest,node_db_config,node_orm,node_postgres,node_api,node_schemas,node_finding_routes,node_cluster_routes,node_graph_routes,node_health_routes toneMint
class node_spa,node_main_ui,node_particles,node_hulls,node_camera,node_graph_ui toneRose
class node_analyst toneIndigo
```

## Components

### Data preparation

- [LUNA16 annotations](https://github.com/technometer/lung-analysis-demo/blob/main/data/raw/annotations.csv): `data/raw/annotations.csv`
- [Cleaning pipeline](https://github.com/technometer/lung-analysis-demo/blob/main/src/data/clean_pipeline.py): `src/data/clean_pipeline.py`
- [Clean findings](https://github.com/technometer/lung-analysis-demo/blob/main/data/processed/clean_findings.csv): `data/processed/clean_findings.csv`

### Finding analysis

- [Unsupervised baseline](https://github.com/technometer/lung-analysis-demo/blob/main/src/models/train_baseline.py): `src/models/train_baseline.py`
- [Enriched findings](https://github.com/technometer/lung-analysis-demo/blob/main/data/processed/enriched_findings.csv): `data/processed/enriched_findings.csv`
- [Fitted models](https://github.com/technometer/lung-analysis-demo/tree/main/models): `models`

### API and storage

- [Relational ingestion](https://github.com/technometer/lung-analysis-demo/blob/main/src/database/ingest_data.py): `src/database/ingest_data.py`
- [DB sessions](https://github.com/technometer/lung-analysis-demo/blob/main/src/database/connection.py): `src/database/connection.py`
- [Study and finding models](https://github.com/technometer/lung-analysis-demo/blob/main/src/database/models.py): `src/database/models.py`
- **PostgreSQL**
- [FastAPI application](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/main.py): `src/api/main.py`
- [API data contracts](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/schemas.py): `src/api/schemas.py`
- [Spatial findings API](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/findings.py): `src/api/routes/findings.py`
- [Cohort summary API](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/clusters.py): `src/api/routes/clusters.py`
- [Knowledge graph API](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/graph.py): `src/api/routes/graph.py`
- [Health API](https://github.com/technometer/lung-analysis-demo/blob/main/src/api/routes/health.py): `src/api/routes/health.py`

### Interactive interface

- [Browser interface](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/index.html): `frontend/index.html`
- [3D scene and controls](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/main.js): `frontend/js/main.js`
- [Finding meshes](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/particles.js): `frontend/js/particles.js`
- [Anatomical context](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/anatomicalHull.js): `frontend/js/anatomicalHull.js`
- [Camera transitions](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/cameraManager.js): `frontend/js/cameraManager.js`
- [2D knowledge graph](https://github.com/technometer/lung-analysis-demo/blob/main/frontend/js/knowledgeGraph.js): `frontend/js/knowledgeGraph.js`

### Other components

- **Clinical analyst**

## Connections

- Cleaning pipeline → LUNA16 annotations: reads
- Cleaning pipeline → Clean findings: writes
- Unsupervised baseline → Clean findings: reads
- Unsupervised baseline → Enriched findings: writes
- Unsupervised baseline → Fitted models: saves
- Relational ingestion → Enriched findings: reads
- Relational ingestion → DB sessions: uses sessions
- Relational ingestion → Study and finding models: creates records
- Relational ingestion → PostgreSQL: writes
- FastAPI application → Spatial findings API: registers
- FastAPI application → Cohort summary API: registers
- FastAPI application → Knowledge graph API: registers
- FastAPI application → Health API: registers
- FastAPI application → Browser interface: serves
- Spatial findings API → DB sessions: gets sessions
- Cohort summary API → DB sessions: gets sessions
- Knowledge graph API → DB sessions: gets sessions
- Health API → DB sessions: gets sessions
- DB sessions → PostgreSQL: connects
- Spatial findings API → Study and finding models: queries findings
- Cohort summary API → Study and finding models: aggregates findings
- Knowledge graph API → Study and finding models: queries studies and findings
- Health API → PostgreSQL: checks connectivity
- Spatial findings API → API data contracts: serializes response
- Cohort summary API → API data contracts: serializes response
- Knowledge graph API → API data contracts: serializes response
- Clinical analyst → Browser interface: uses
- Browser interface → 3D scene and controls: loads
- 3D scene and controls → Spatial findings API: requests spatial findings
- 3D scene and controls → Cohort summary API: requests cohort metrics
- 3D scene and controls → Finding meshes: creates finding meshes
- 3D scene and controls → Anatomical context: creates anatomy
- 3D scene and controls → Camera transitions: focuses camera
- 3D scene and controls → 2D knowledge graph: opens graph
- 2D knowledge graph → Knowledge graph API: requests study graph