# mutentman/pneumonia-detection-deep-cnn architecture

> Architecture diagram of the GitHub repository mutentman/pneumonia-detection-deep-cnn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mutentman/pneumonia-detection-deep-cnn
- Repository: https://github.com/mutentman/pneumonia-detection-deep-cnn

## Overview

#### Purpose and Entry Points
This repository trains and serves a TensorFlow/Keras CNN for binary pneumonia detection from chest X-ray images. Training starts at `src/train.py`; model architecture and image-pipeline logic are separated into `src/model.py` and `src/dataset.py`. User-facing inference entry points appear to be `streamlit_app.py` and `src/app.py`, with an HTML template at `templates/index.html`.

#### Dataset Ingestion and Augmentation
`src/dataset.py` owns loading the Kaggle Chest X-Ray Images (Pneumonia) dataset and constructing image generators. The expected external dataset boundary is local, untracked image data under `data/raw/chest_xray/{train,test,val}`. Training-time augmentation is used to improve robustness and mitigate class imbalance before batches reach the network.

Paths: `src/dataset.py`, `src/train.py`

#### CNN Model Definition
`src/model.py` defines the core 11-layer sequential CNN. The architecture uses convolutional layers with batch normalization and dropout, producing a binary pneumonia/non-pneumonia prediction. This module should remain independent of dataset paths and UI concerns so training and inference can load the same model definition or serialized artifact.

Paths: `src/model.py`, `saved_models/best_model.keras`

#### Training, Validation, and Model Selection
`src/train.py` is the orchestration boundary: it obtains data generators, builds/compiles the model, executes fitting, validates performance, and evaluates the held-out test split. Early stopping and checkpointing select the best validation-stage model rather than relying only on the final epoch. Training produces history artifacts such as loss/accuracy plots and persists the selected Keras model.

Paths: `src/train.py`, `src/dataset.py`, `saved_models/best_model.keras`

#### Persisted Model Boundary
The trained model is serialized as a Keras artifact and consumed separately from training. `saved_models/best_model.keras` is the current packaged inference asset. In normal development, model artifacts are generated from the external dataset and should be treated as versioned runtime inputs to serving applications, not source code.

Paths: `saved_models/best_model.keras`, `src/train.py`

#### Inference and Presentation Layer
The repository contains two likely serving surfaces: a Streamlit interface in `streamlit_app.py` and an application module in `src/app.py`; the latter is associated with `templates/index.html`, suggesting a server-rendered upload/inference interface. These layers should load the persisted Keras model, preprocess a user-supplied X-ray consistently with the training pipeline, run prediction, and present the classification result. They are downstream of, and should not trigger, training.

Paths: `streamlit_app.py`, `src/app.py`, `templates/index.html`

#### Runtime and External Dependencies
Python is the runtime (`runtime.txt`), with dependencies declared in `requirements.txt`. Material external dependencies are TensorFlow/Keras for CNN training/inference, the Kaggle-hosted chest-X-ray dataset for model development, and the local filesystem for raw images and saved model artifacts. No database, queue, or cloud service is indicated by the repository tree.

Paths: `requirements.txt`, `runtime.txt`, `README.md`

Main entry points: [`src/train.py`](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/train.py) (Training orchestration), [`src/app.py`](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/app.py) (Server application), [`requirements.txt`](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/requirements.txt) (TensorFlow/Keras), [`saved_models/best_model.keras`](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/saved_models/best_model.keras) (Best Keras model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training pipeline"]
  node_raw_dataset[("Chest X-ray images<br/>external dataset")]
  node_dataset_pipeline["Dataset generators<br/>image pipeline<br/>[dataset.py]"]
  node_model_definition["11-layer CNN<br/>Keras model<br/>[model.py]"]
  node_training_orchestrator["Training orchestration<br/>training entry point<br/>[train.py]"]
end

subgraph group_serving["Inference surfaces"]
  node_streamlit_ui["Streamlit UI<br/>interactive serving entry point<br/>[streamlit_app.py]"]
  node_server_app["Server application<br/>web serving entry point<br/>[app.py]"]
  node_html_template["Upload result page<br/>HTML template<br/>[index.html]"]
  node_user_xray["User-supplied X-ray<br/>upload input"]
end

node_model_artifact["Best Keras model<br/>serialized model<br/>[best_model.keras]"]
node_tensorflow["TensorFlow/Keras<br/>ML framework<br/>[requirements.txt]"]
node_python_runtime["Python runtime<br/>[runtime.txt]"]

node_raw_dataset -->|"loads image splits"| node_dataset_pipeline
node_dataset_pipeline -->|"batches and augmentation"| node_training_orchestrator
node_model_definition -->|"builds and compiles"| node_training_orchestrator
node_tensorflow -.->|"image generators"| node_dataset_pipeline
node_tensorflow -.->|"CNN layers"| node_model_definition
node_tensorflow -.->|"fit and evaluate"| node_training_orchestrator
node_training_orchestrator -->|"checkpoints selected model"| node_model_artifact
node_user_xray -->|"upload"| node_streamlit_ui
node_user_xray -->|"upload"| node_server_app
node_model_artifact -->|"loads for prediction"| node_streamlit_ui
node_model_artifact -->|"loads for prediction"| node_server_app
node_html_template -->|"renders results"| node_server_app
node_python_runtime -.->|"runs"| node_streamlit_ui
node_python_runtime -.->|"runs"| node_server_app

click node_dataset_pipeline "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/dataset.py"
click node_model_definition "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/model.py"
click node_training_orchestrator "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/train.py"
click node_model_artifact "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/saved_models/best_model.keras"
click node_tensorflow "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/requirements.txt"
click node_streamlit_ui "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/streamlit_app.py"
click node_server_app "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/app.py"
click node_html_template "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/templates/index.html"
click node_python_runtime "https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/runtime.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_raw_dataset,node_dataset_pipeline,node_model_definition,node_training_orchestrator toneBlue
class node_streamlit_ui,node_server_app,node_html_template,node_user_xray toneAmber
class node_model_artifact,node_tensorflow,node_python_runtime toneNeutral
```

## Components

### Training pipeline

- **Chest X-ray images**: external dataset · Local untracked train, validation, and test image splits.
- [Dataset generators](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/dataset.py): image pipeline · Loads images and applies training augmentation. · `src/dataset.py`
- [11-layer CNN](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/model.py): Keras model · Binary pneumonia classifier definition. · `src/model.py`
- [Training orchestration](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/train.py): training entry point · Fits, validates, evaluates, and selects the best model. · `src/train.py`

### Inference surfaces

- [Streamlit UI](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/streamlit_app.py): interactive serving entry point · Accepts an X-ray and presents a prediction. · `streamlit_app.py`
- [Server application](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/src/app.py): web serving entry point · Handles upload and inference requests. · `src/app.py`
- [Upload result page](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/templates/index.html): HTML template · `templates/index.html`
- **User-supplied X-ray**: upload input

### Other components

- [Best Keras model](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/saved_models/best_model.keras): serialized model · Selected model used by inference applications. · `saved_models/best_model.keras`
- [TensorFlow/Keras](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/requirements.txt): ML framework · `requirements.txt`
- [Python runtime](https://github.com/mutentman/pneumonia-detection-deep-cnn/blob/main/runtime.txt): runtime · `runtime.txt`

## Connections

- Chest X-ray images → Dataset generators: loads image splits
- Dataset generators → Training orchestration: batches and augmentation
- 11-layer CNN → Training orchestration: builds and compiles
- TensorFlow/Keras → Dataset generators: image generators
- TensorFlow/Keras → 11-layer CNN: CNN layers
- TensorFlow/Keras → Training orchestration: fit and evaluate
- Training orchestration → Best Keras model: checkpoints selected model
- User-supplied X-ray → Streamlit UI: upload
- User-supplied X-ray → Server application: upload
- Best Keras model → Streamlit UI: loads for prediction
- Best Keras model → Server application: loads for prediction
- Upload result page → Server application: renders results
- Python runtime → Streamlit UI: runs
- Python runtime → Server application: runs