How codecxab/final-year-project-cnn-ensemble works
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: main.py API Entry · docker-compose.yml Compose · telegram_bot.py Telegram Bot · ai_pipeline.py AI Pipeline
Components 19
Deployment
Compose-based multi-service runtime
- Compose · Defines the multi-service stack
docker-compose.yml - UI Docker · Container image definition for the Next.js app
frontend-nextjs/Dockerfile - API Docker · Container image definition for backend service
backend/Dockerfile
Clients
User-facing entry points
- Next.js UI · Primary browser dashboard and visualization app
frontend-nextjs/src/app - Streamlit UI · Alternative lightweight user interface
frontend-streamlit/app.py - Telegram Bot · Chat-based interaction channel
bot/telegram_bot.py - Bot Req · Python dependencies for the Telegram bot
bot/requirements.txt
Backend
FastAPI orchestration and API
- API Entry · Backend service entry point
backend/main.py - AI Pipeline · Coordinates prediction workflow
backend/ai_pipeline.py - Scan Parser · Handles CT file parsing and preparation
backend/document_parser.py - Agent Flow · LangGraph-based multi-step coordination
backend/langgraph_agent.py - Backend Req · Python dependencies for the API service
backend/requirements.txt
ML System
Inference code and trained artifacts
- Model Weights · Trained lung nodule model artifact
machine_learning/models/best_lung_nodule_model.pth - ML Artifacts · Plots and supporting experiment artifacts
machine_learning/plots
Storage
Local persistence and file staging
- Database · Persistence abstraction for local records
backend/database.py - LungCare DB · Local SQLite database file
backend/lungcare.db - Uploads · Local storage for incoming scan files
backend/uploads
Operations
Repo-level startup and shared config
- Start All · Convenience script to boot services
start_all.py - Env Example · Template for runtime configuration
.env.example
Connections 21
- 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