# codecxab/final-year-project-cnn-ensemble architecture

> Architecture diagram of the GitHub repository codecxab/final-year-project-cnn-ensemble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codecxab/final-year-project-cnn-ensemble
- Repository: https://github.com/codecxab/final-year-project-cnn-ensemble

## Overview

1. **Repository shape**
   - This is a monorepo for a lung nodule / lung cancer detection system called **LungCare**.
   - It contains a trained ML model artifact, a Python backend, two separate frontends, and a Telegram bot integration.
   - The main runtime boundary is: **UI clients → FastAPI backend → ML inference / persistence**.

2. **Primary application flow**
   - The core user path is uploading or submitting a **3D CT scan file** (the README calls out `.mhd` handling).
   - The backend parses the scan, runs it through the prediction pipeline, stores or references results in a local database, and returns prediction output for visualization or review.
   - The frontend consumes these results to present the dashboard and 3D visualization.

3. **Backend service**
   - `backend/main.py` is the entry point for the API and likely hosts the FastAPI application described in the README.
   - `backend/requirements.txt` and `backend/Dockerfile` indicate this is containerized and can run standalone.
   - The backend is the main orchestration layer for requests, inference, and any auxiliary workflow logic.

4. **Inference and AI pipeline**
   - `backend/ai_pipeline.py` is the likely inference orchestration module.
   - The ML asset in `machine_learning/models/best_lung_nodule_model.pth` suggests the backend loads a PyTorch model checkpoint for prediction.
   - The README describes an **ensemble of 3D CNNs** with soft-voting; that ensemble behavior is presumably encapsulated in the pipeline rather than exposed to the UI.

5. **Scan parsing and preprocessing**
   - `backend/document_parser.py` is the dedicated boundary for turning uploaded medical imaging files into usable data.
   - Given the README emphasis on `.mhd`, this module likely handles file decoding, slice extraction, normalization, or other preprocessing before inference.
   - This is an important separation: file-format handling is isolated from model execution.

6. **Workflow / agent layer**
   - `backend/langgraph_agent.py` indicates an agentic workflow layer built with LangGraph.
   - This suggests some backend actions are coordinated through a graph-based or stateful process, likely for multi-step analysis or decision logic.
   - Architecturally, this sits above raw inference and may mediate how results are generated or summarized.

7. **Persistence layer**
   - `backend/database.py` is the database abstraction, and `backend/lungcare.db` shows the project uses a **local SQLite database**.
   - This is probably used for storing scan metadata, prediction results, user/session records, or audit-style history.
   - The presence of a local DB implies the backend is designed for lightweight deployment rather than a separate database server.

8. **File storage**
   - `backend/uploads/` is the local upload staging area for incoming imaging files.
   - That means the file flow is likely: upload to backend → save to disk → parse/process → optionally persist metadata/results in SQLite.
   - This folder is part of the backend’s stateful boundary and should be considered when diagramming storage.

9. **Web frontend**
   - `frontend-nextjs/` is the primary user interface, built with **Next.js** and TypeScript.
   - The README describes a dark, healthcare-oriented dashboard UI with 3D visualization and interaction.
   - Its role is presentation only: it should be diagrammed as a client consuming backend APIs, not as a compute layer.

10. **Alternative frontend**
   - `frontend-streamlit/` is a separate Streamlit app, likely an earlier prototype or alternate interface.
   - Because it is packaged independently with its own requirements, it should be treated as a parallel UI option rather than part of the main production stack.
   - For an architecture diagram, keep it separate from the Next.js app unless you want to show “alternative UI” branches.

11. **Telegram bot**
   - `bot/telegram_bot.py` plus its own requirements indicate an external messaging interface.
   - This is likely a secondary channel for interaction or notification, probably calling into the same backend logic or database.
   - If diagramming, show it as an external client/service that connects to the backend, not directly to the ML model.

12. **Orchestration and deployment**
   - `docker-compose.yml`, per-service Dockerfiles, and `start_all.py` show the repo is intended to be run as a multi-service system.
   - The README explicitly describes Docker Compose as the easiest setup, with frontend on port 3000 and backend API docs on port 8000.
   - That makes Docker Compose the top-level deployment boundary across services.

13. **Model and experiment artifacts**
   - `machine_learning/models/` contains the trained weights, and `machine_learning/plots/` suggests training/evaluation outputs.
   - These artifacts are not runtime services, but they are part of the ML supply chain feeding the backend inference layer.
   - For architecture purposes, they belong in a “model artifacts” boundary adjacent to the backend pipeline.

14. **Operational notes**
   - `requirements.txt` at the repo root and `build_history.py` suggest there may be shared tooling or history/version tracking outside the main app services.
   - The repo also includes `.env.example`, implying configuration is externalized through environment variables.
   - This supports a deployable, container-friendly architecture with configuration injected at runtime.

15. **Overall diagram takeaway**
   - The clearest architecture is: **users or clinicians interact through the Next.js UI or Streamlit/Telegram interfaces; those clients call the FastAPI backend; the backend parses CT uploads, runs ML inference using the packaged model artifacts and ensemble logic, stores state in SQLite and local upload storage, and returns predictions for visualization or follow-up**.
   - The main boundaries are **client/UI**, **backend API**, **ML inference pipeline**, and **local persistence/storage**.

Main entry points: [`backend/main.py`](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/main.py) (API Entry), [`docker-compose.yml`](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/docker-compose.yml) (Compose), [`bot/telegram_bot.py`](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/bot/telegram_bot.py) (Telegram Bot), [`backend/ai_pipeline.py`](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/ai_pipeline.py) (AI Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_docker_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_frontend_docker["UI Docker<br/>container build"]
  node_backend_docker["API Docker<br/>container build"]
end

subgraph group_clients["Clients"]
  node_nextjs_ui["Next.js UI<br/>web client"]
  node_streamlit_ui["Streamlit UI<br/>alt client<br/>[app.py]"]
  node_telegram_bot["Telegram Bot<br/>messaging client<br/>[telegram_bot.py]"]
  node_bot_req["Bot Req<br/>dependencies<br/>[requirements.txt]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API Entry<br/>FastAPI app<br/>[main.py]"]
  node_ai_pipeline["AI Pipeline<br/>inference orchestrator<br/>[ai_pipeline.py]"]
  node_doc_parser["Scan Parser<br/>preprocess<br/>[document_parser.py]"]
  node_agent["Agent Flow<br/>workflow<br/>[langgraph_agent.py]"]
  node_backend_req["Backend Req<br/>dependencies<br/>[requirements.txt]"]
end

subgraph group_ml["ML System"]
  node_model_weights["Model Weights<br/>pytorch checkpoint"]
  node_ml_artifacts["ML Artifacts<br/>training outputs"]
end

subgraph group_storage["Storage"]
  node_db_layer[("Database<br/>sqlite access<br/>[database.py]")]
  node_sqlite_db[("LungCare DB<br/>sqlite file<br/>[lungcare.db]")]
  node_uploads["Uploads<br/>file staging"]
end

subgraph group_ops["Operations"]
  node_start_all["Start All<br/>launcher<br/>[start_all.py]"]
  node_env_example["Env Example<br/>config<br/>[.env.example]"]
end

node_docker_compose -->|"runs API"| node_backend_main
node_docker_compose -->|"runs UI"| node_nextjs_ui
node_docker_compose -->|"runs alt UI"| node_streamlit_ui
node_docker_compose -->|"runs bot"| node_telegram_bot
node_start_all -->|"orchestrates"| node_docker_compose
node_env_example -->|"configures"| node_docker_compose
node_nextjs_ui -->|"calls API"| node_backend_main
node_streamlit_ui -->|"calls API"| node_backend_main
node_telegram_bot -->|"invokes"| node_backend_main
node_backend_main -->|"parses scan"| node_doc_parser
node_backend_main -->|"coordinates"| node_agent
node_agent -->|"triggers"| node_ai_pipeline
node_ai_pipeline -->|"loads model"| node_model_weights
node_ai_pipeline -->|"references"| node_ml_artifacts
node_doc_parser -->|"reads/writes"| node_uploads
node_backend_main -->|"persists"| node_db_layer
node_db_layer -->|"uses"| node_sqlite_db
node_backend_main -->|"depends on"| node_backend_req
node_telegram_bot -->|"depends on"| node_bot_req
node_backend_docker -->|"packages"| node_backend_main
node_frontend_docker -->|"packages"| node_nextjs_ui

click node_docker_compose "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/docker-compose.yml"
click node_start_all "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/start_all.py"
click node_env_example "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/.env.example"
click node_nextjs_ui "https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/frontend-nextjs/src/app"
click node_streamlit_ui "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/frontend-streamlit/app.py"
click node_telegram_bot "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/bot/telegram_bot.py"
click node_backend_main "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/main.py"
click node_ai_pipeline "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/ai_pipeline.py"
click node_doc_parser "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/document_parser.py"
click node_agent "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/langgraph_agent.py"
click node_db_layer "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/database.py"
click node_sqlite_db "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/lungcare.db"
click node_uploads "https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/backend/uploads"
click node_model_weights "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/machine_learning/models/best_lung_nodule_model.pth"
click node_ml_artifacts "https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/machine_learning/plots"
click node_backend_req "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/requirements.txt"
click node_bot_req "https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/bot/requirements.txt"
click node_frontend_docker "https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/frontend-nextjs/Dockerfile"
click node_backend_docker "https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/backend/Dockerfile"

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_docker_compose,node_frontend_docker,node_backend_docker toneBlue
class node_nextjs_ui,node_streamlit_ui,node_telegram_bot,node_bot_req toneAmber
class node_backend_main,node_ai_pipeline,node_doc_parser,node_agent,node_backend_req toneMint
class node_model_weights,node_ml_artifacts toneRose
class node_db_layer,node_sqlite_db,node_uploads toneIndigo
class node_start_all,node_env_example toneTeal
```

## Components

### Deployment

Compose-based multi-service runtime

- [Compose](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/docker-compose.yml): orchestration · Defines the multi-service stack · `docker-compose.yml`
- [UI Docker](https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/frontend-nextjs/Dockerfile): container build · Container image definition for the Next.js app · `frontend-nextjs/Dockerfile`
- [API Docker](https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/backend/Dockerfile): container build · Container image definition for backend service · `backend/Dockerfile`

### Clients

User-facing entry points

- [Next.js UI](https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/frontend-nextjs/src/app): web client · Primary browser dashboard and visualization app · `frontend-nextjs/src/app`
- [Streamlit UI](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/frontend-streamlit/app.py): alt client · Alternative lightweight user interface · `frontend-streamlit/app.py`
- [Telegram Bot](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/bot/telegram_bot.py): messaging client · Chat-based interaction channel · `bot/telegram_bot.py`
- [Bot Req](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/bot/requirements.txt): dependencies · Python dependencies for the Telegram bot · `bot/requirements.txt`

### Backend

FastAPI orchestration and API

- [API Entry](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/main.py): FastAPI app · Backend service entry point · `backend/main.py`
- [AI Pipeline](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/ai_pipeline.py): inference orchestrator · Coordinates prediction workflow · `backend/ai_pipeline.py`
- [Scan Parser](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/document_parser.py): preprocess · Handles CT file parsing and preparation · `backend/document_parser.py`
- [Agent Flow](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/langgraph_agent.py): workflow · LangGraph-based multi-step coordination · `backend/langgraph_agent.py`
- [Backend Req](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/requirements.txt): dependencies · Python dependencies for the API service · `backend/requirements.txt`

### ML System

Inference code and trained artifacts

- [Model Weights](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/machine_learning/models/best_lung_nodule_model.pth): pytorch checkpoint · Trained lung nodule model artifact · `machine_learning/models/best_lung_nodule_model.pth`
- [ML Artifacts](https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/machine_learning/plots): training outputs · Plots and supporting experiment artifacts · `machine_learning/plots`

### Storage

Local persistence and file staging

- [Database](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/database.py): sqlite access · Persistence abstraction for local records · `backend/database.py`
- [LungCare DB](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/backend/lungcare.db): sqlite file · Local SQLite database file · `backend/lungcare.db`
- [Uploads](https://github.com/codecxab/final-year-project-cnn-ensemble/tree/main/backend/uploads): file staging · Local storage for incoming scan files · `backend/uploads`

### Operations

Repo-level startup and shared config

- [Start All](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/start_all.py): launcher · Convenience script to boot services · `start_all.py`
- [Env Example](https://github.com/codecxab/final-year-project-cnn-ensemble/blob/main/.env.example): config · Template for runtime configuration · `.env.example`

## Connections

- Compose → API Entry: runs API · Compose starts the backend service
- Compose → Next.js UI: runs UI · Compose starts the main web frontend
- Compose → Streamlit UI: runs alt UI · Compose can include the Streamlit interface
- Compose → Telegram Bot: runs bot · Compose can launch the Telegram integration
- Start All → Compose: orchestrates · Helper script boots the composed stack
- Env Example → Compose: configures · Environment values feed service setup
- Next.js UI → API Entry: calls API · Browser app submits scans and fetches predictions
- Streamlit UI → API Entry: calls API · Alternative frontend uses the same backend
- Telegram Bot → API Entry: invokes · Bot routes user actions into backend logic
- API Entry → Scan Parser: parses scan · API hands uploaded CT files to preprocessing
- API Entry → Agent Flow: coordinates · Requests may pass through workflow orchestration
- Agent Flow → AI Pipeline: triggers · Workflow delegates prediction work to the pipeline
- AI Pipeline → Model Weights: loads model · Inference uses the trained checkpoint
- AI Pipeline → ML Artifacts: references · Training artifacts support the ML system
- Scan Parser → Uploads: reads/writes · Incoming scans are staged on disk
- API Entry → Database: persists · API stores and retrieves result metadata
- Database → LungCare DB: uses · Database abstraction targets the local SQLite file
- API Entry → Backend Req: depends on · Backend runtime dependencies
- Telegram Bot → Bot Req: depends on · Bot runtime dependencies
- API Docker → API Entry: packages · Backend container image builds the API app
- UI Docker → Next.js UI: packages · Frontend container image builds the Next.js app
