# manishkumarsingh41/luminapath-ai-retinal-disease-detection architecture

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

- Interactive diagram: https://gitdiagram.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection
- Repository: https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection

## Overview

#### Purpose and Runtime Entry Point
LuminaPath is a local Python/Streamlit application for classifying retinal OCT images with a trained CNN, presenting confidence and explanatory text, and producing downloadable medical PDF reports. The operational entry point is `frontend/app.py`, launched with `streamlit run frontend/app.py`.

#### Presentation and Interaction Layer
The Streamlit UI orchestrates the user workflow: scan upload, language selection, prediction display, explanation display, and report download. Its principal composition root is `frontend/app.py`, with feature-level UI boundaries in:
- `frontend/components/upload_section.py`
- `frontend/components/prediction_view.py`
- `frontend/components/report_download.py`

Styling is locally supplied through `frontend/assets/styles.css`; no browser SPA, separate API server, or cloud frontend is indicated.

#### Image Intake Boundary
Uploaded OCT images are accepted by the frontend and passed into backend inference/reporting flows. The accepted image formats are JPG, JPEG, and PNG. Upload handling is isolated in `frontend/components/upload_section.py`, providing a natural boundary for validation, image-size limits, and future patient-data handling.

#### Model Inference Pipeline
The CNN inference subsystem loads and evaluates the packaged Keras HDF5 model at `models/retinal_cnn_model.h5`. `backend/model_inference.py` is the core model boundary and is responsible for preprocessing input images, invoking TensorFlow/Keras prediction, and returning disease prediction plus confidence information.

The model artifact is versioned in-repository rather than fetched from a model registry or external inference service.

#### Application Service/API Layer
`backend/api.py` is the backend-facing integration layer between UI orchestration and domain services. It is the likely contract boundary for prediction-related calls, insulating Streamlit components from model implementation details. The repository is a single-process application structure: “backend” modules are Python modules consumed by the Streamlit process, not evidence of a separately deployed HTTP API.

#### Explanation and Localization Stage
Prediction results feed an explanation view, with language choice handled independently from rendering:
- `frontend/components/language_selector.py`
- `frontend/components/explanation_view.py`

This stage converts raw classification output into practitioner-facing explanatory content and supports multi-language presentation. It should remain downstream of inference so localization does not affect model inputs or outputs.

#### Report Generation and Delivery
`backend/report_generator.py` produces structured PDF reports from the uploaded scan context and inference result. `frontend/components/report_download.py` exposes the generated artifact to the user. The README states report generation can trigger automatic prediction, so report creation depends on, or can initiate, the inference pipeline rather than trusting only a displayed UI result.

#### Material Dependencies and External Boundaries
Core runtime technologies are Python, Streamlit, TensorFlow/Keras, and PDF-generation dependencies declared in `requirements.txt`. The only supplied ML infrastructure is the local `.h5` model artifact. No database, authentication provider, cloud storage, hospital integration, remote model endpoint, or external API is documented. As a medical-support workflow, image uploads, predictions, and generated reports are the sensitive data boundaries.

Main entry points: [`frontend/app.py`](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/app.py) (Streamlit App), [`backend/api.py`](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/api.py) (Backend API), [`backend/report_generator.py`](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/report_generator.py) (PDF Report Generator), [`backend/model_inference.py`](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/model_inference.py) (Model Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit UI"]
  node_app["Streamlit App<br/>composition root<br/>[app.py]"]
  node_upload["Upload Section<br/>upload boundary<br/>[upload_section.py]"]
  node_language["Language Selector<br/>UI component"]
  node_prediction_view["Prediction View<br/>UI component<br/>[prediction_view.py]"]
  node_explanation_view["Explanation View<br/>UI component"]
  node_report_download["Report Download<br/>UI component<br/>[report_download.py]"]
  node_styles["UI Styles<br/>stylesheet<br/>[styles.css]"]
end

subgraph group_backend["Backend Services"]
  node_api["Backend API<br/>integration layer<br/>[api.py]"]
  node_inference["Model Inference<br/>CNN inference service<br/>[model_inference.py]"]
  node_model{{"Retinal CNN Model<br/>Keras HDF5 artifact"}}
  node_report_generator["PDF Report Generator<br/>report service"]
end

node_user(("Clinician/User<br/>actor"))
node_pdf_report["Generated PDF Report<br/>sensitive artifact"]
node_requirements["Runtime Dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_user -->|"uses"| node_app
node_app -->|"composes"| node_upload
node_app -->|"composes"| node_language
node_app -->|"composes"| node_prediction_view
node_app -->|"composes"| node_explanation_view
node_app -->|"composes"| node_report_download
node_app -->|"applies"| node_styles
node_upload -->|"uploaded scan"| node_api
node_language -->|"selected language"| node_explanation_view
node_api -->|"prediction request"| node_inference
node_inference -->|"loads and evaluates"| node_model
node_api -->|"prediction and confidence"| node_prediction_view
node_api -->|"classification result"| node_explanation_view
node_api -->|"report request"| node_report_generator
node_report_generator -.->|"can trigger prediction"| node_inference
node_report_generator -->|"generates"| node_pdf_report
node_pdf_report -->|"download artifact"| node_report_download
node_requirements -.->|"runtime packages"| node_app
node_requirements -.->|"ML packages"| node_inference
node_requirements -.->|"PDF packages"| node_report_generator

click node_app "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/app.py"
click node_upload "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/upload_section.py"
click node_language "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/language_selector.py"
click node_prediction_view "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/prediction_view.py"
click node_explanation_view "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/explanation_view.py"
click node_report_download "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/report_download.py"
click node_styles "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/assets/styles.css"
click node_api "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/api.py"
click node_inference "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/model_inference.py"
click node_model "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/models/retinal_cnn_model.h5"
click node_report_generator "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/report_generator.py"
click node_requirements "https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/requirements.txt"

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_app,node_upload,node_language,node_prediction_view,node_explanation_view,node_report_download,node_styles toneBlue
class node_api,node_inference,node_model,node_report_generator toneAmber
class node_user,node_pdf_report,node_requirements toneNeutral
```

## Components

### Streamlit UI

Local user workflow and presentation.

- [Streamlit App](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/app.py): composition root · Launch with Streamlit; orchestrates the local workflow. · `frontend/app.py`
- [Upload Section](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/upload_section.py): upload boundary · Accepts JPG, JPEG, and PNG OCT scans. · `frontend/components/upload_section.py`
- [Language Selector](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/language_selector.py): UI component · `frontend/components/language_selector.py`
- [Prediction View](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/prediction_view.py): UI component · `frontend/components/prediction_view.py`
- [Explanation View](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/explanation_view.py): UI component · Renders localized practitioner-facing content. · `frontend/components/explanation_view.py`
- [Report Download](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/components/report_download.py): UI component · Offers generated PDF reports to the user. · `frontend/components/report_download.py`
- [UI Styles](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/frontend/assets/styles.css): stylesheet · `frontend/assets/styles.css`

### Backend Services

In-process domain and inference services.

- [Backend API](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/api.py): integration layer · In-process contract between UI and domain services. · `backend/api.py`
- [Model Inference](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/model_inference.py): CNN inference service · Preprocesses scans and returns prediction with confidence. · `backend/model_inference.py`
- [Retinal CNN Model](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/models/retinal_cnn_model.h5): Keras HDF5 artifact · Packaged local model artifact. · `models/retinal_cnn_model.h5`
- [PDF Report Generator](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/backend/report_generator.py): report service · Builds reports from scan context and inference results. · `backend/report_generator.py`

### Other components

- **Clinician/User**: actor
- **Generated PDF Report**: sensitive artifact
- [Runtime Dependencies](https://github.com/manishkumarsingh41/luminapath-ai-retinal-disease-detection/blob/main/requirements.txt): dependency manifest · Declares Streamlit, TensorFlow/Keras, and PDF dependencies. · `requirements.txt`

## Connections

- Clinician/User → Streamlit App: uses
- Streamlit App → Upload Section: composes
- Streamlit App → Language Selector: composes
- Streamlit App → Prediction View: composes
- Streamlit App → Explanation View: composes
- Streamlit App → Report Download: composes
- Streamlit App → UI Styles: applies
- Upload Section → Backend API: uploaded scan
- Language Selector → Explanation View: selected language
- Backend API → Model Inference: prediction request
- Model Inference → Retinal CNN Model: loads and evaluates
- Backend API → Prediction View: prediction and confidence
- Backend API → Explanation View: classification result
- Backend API → PDF Report Generator: report request
- PDF Report Generator → Model Inference: can trigger prediction
- PDF Report Generator → Generated PDF Report: generates
- Generated PDF Report → Report Download: download artifact
- Runtime Dependencies → Streamlit App: runtime packages
- Runtime Dependencies → Model Inference: ML packages
- Runtime Dependencies → PDF Report Generator: PDF packages