# joberthcastro/ia-diagnostico-pneumonia architecture

> Architecture diagram of the GitHub repository joberthcastro/ia-diagnostico-pneumonia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joberthcastro/ia-diagnostico-pneumonia
- Repository: https://github.com/joberthcastro/ia-diagnostico-pneumonia

## Overview

##### Project Type and Purpose
- This is a standalone machine-learning image classification pipeline implemented in Python (no separate frontend/backend).
- Its goal is to train, validate, test, and evaluate a convolutional neural network (CNN) for binary classification of chest X-ray images (normal vs. viral pneumonia).

##### File Structure Analysis
- `Dataset/` contains three subfolders (`Train`, `Val`, `Test`), each split into `Normal_Radiografia` and `Viral_Radiografia`.
- The single script `pneumonia_classifier.py` orchestrates data loading, preprocessing, model definition, training, evaluation, and artifact generation.
- `requirements.txt` lists the Python dependencies (TensorFlow/Keras, OpenCV, NumPy, Matplotlib, Seaborn, scikit-learn, pandas).

##### Architecture Insights from README
- A CNN with 3 convolutional+ReLU+MaxPooling layers, dense layers with dropout, and sigmoid output for binary classification.
- Preprocessing pipeline: grayscale conversion → histogram equalization → Gaussian blur → normalization → resizing to 225×225.
- Training: 15 epochs, data augmentation, early stopping, best model saved (`best_model.h5`).
- Outputs: training history plot, confusion matrix, per-class metrics chart, ROC curve.

##### Main Components
a. Data Ingestion & Splitting
- Raw images (`Train/`, `Val/`, `Test/`)
b. Preprocessing Pipeline
- Grayscale → Equalization → Denoising → Normalization → Resize
c. Data Augmentation Module
- On-the-fly random transformations (rotation, shift, flip, etc.)
d. Model Definition
- Sequential CNN layers + dense layers + dropout → sigmoid output
e. Training Engine
- Epoch loop, optimizer, loss function, callbacks (EarlyStopping, ModelCheckpoint)
f. Evaluation & Metrics
- Predict on test set → compute accuracy, precision/recall/F1, confusion matrix, ROC/AUC
g. Artifacts & Outputs
- Saved model (`best_model.h5`), plots (`training_history.png`, `confusion_matrix.png`, `classification_metrics.png`, `roc_curve.png`)

##### Relationships and Data Flow
- Preprocessed data feeds into Model Definition & Training Engine
- Training Engine outputs checkpoints to Artifact store
- After training, Test data flows through Preprocessing → Model → Evaluation module
- Evaluation produces metrics and plots

##### Architectural Patterns & Design Principles
- Modular pipeline: separate concerns (I/O, preprocessing, augmentation, modeling, evaluation)
- Callback pattern in training (early stopping, checkpointing)
- Batch processing for efficiency
- Reproducibility via fixed random seeds and saved model

##### Technologies & Libraries
- TensorFlow/Keras for model definition/training
- OpenCV for image preprocessing
- NumPy/pandas for data manipulation
- scikit-learn for metrics
- Matplotlib/Seaborn for plotting

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion
    subgraph "Data Ingestion & Splitting"
        datasetTrain["Train Images"]:::data
        datasetVal["Val Images"]:::data
        datasetTest["Test Images"]:::data
    end

    subgraph "Metadata Reference"
        NormalMetadata["Normal.metadata.xlsx"]:::data
        ViralMetadata["Viral Pneumonia.metadata.xlsx"]:::data
    end

    %% Preprocessing Pipeline
    subgraph "Preprocessing Pipeline" 
        Preprocessor_Gray["Grayscale Conversion"]:::process
        Preprocessor_Equal["Histogram Equalization"]:::process
        Preprocessor_Denoise["Gaussian Blur"]:::process
        Preprocessor_Normalize["Normalization"]:::process
        Preprocessor_Resize["Resize to 225×225"]:::process
    end

    %% Data Augmentation
    Augmentor["On-the-fly Data Augmentation"]:::process

    %% Model Definition
    ModelDef["CNN: Conv+ReLU+Pool ×3 → Dense+Dropout → Sigmoid"]:::model

    %% Training Engine
    Trainer["Training Engine\n(epochs, optimizer, loss, callbacks)"]:::model

    %% Artifact Store
    Artifacts["Artifact Outputs\n(best_model.h5, plots)"]:::eval

    %% Evaluation & Metrics
    Evaluator["Evaluation Module\n(metrics + plots)"]:::eval

    %% Documentation
    subgraph "Project Docs & Dependencies"
        README["readme.md"]:::doc
        REQ["requirements.txt"]:::doc
    end

    %% Connections
    datasetTrain -->|"images"| Preprocessor_Gray
    datasetVal --> Preprocessor_Gray
    datasetTest --> Preprocessor_Gray

    NormalMetadata --> datasetTrain
    ViralMetadata --> datasetTrain

    Preprocessor_Gray --> Preprocessor_Equal
    Preprocessor_Equal --> Preprocessor_Denoise
    Preprocessor_Denoise --> Preprocessor_Normalize
    Preprocessor_Normalize --> Preprocessor_Resize

    Preprocessor_Resize -->|"preprocessed images"| Augmentor
    Preprocessor_Resize -->|"preprocessed images"| Evaluator

    Augmentor -->|"augmented tensors"| Trainer
    ModelDef --> Trainer
    Trainer -->|"best_model.h5"| Artifacts

    Artifacts --> ModelDef
    Preprocessor_Resize --> Evaluator
    Artifacts --> Evaluator

    Evaluator -->|"metrics + plots"| Artifacts

    README --- datasetTrain
    REQ --- Trainer

    %% Click Events
    click datasetTrain "https://github.com/joberthcastro/ia-diagnostico-pneumonia/tree/main/Dataset/Train"
    click datasetVal "https://github.com/joberthcastro/ia-diagnostico-pneumonia/tree/main/Dataset/Val"
    click datasetTest "https://github.com/joberthcastro/ia-diagnostico-pneumonia/tree/main/Dataset/Test"
    click NormalMetadata "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/Dataset/Meta_dados/Normal.metadata.xlsx"
    click ViralMetadata "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/Dataset/Meta_dados/Viral Pneumonia.metadata.xlsx"
    click Preprocessor_Gray "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Preprocessor_Equal "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Preprocessor_Denoise "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Preprocessor_Normalize "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Preprocessor_Resize "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Augmentor "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click ModelDef "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Trainer "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Evaluator "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click Artifacts "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/pneumonia_classifier.py"
    click README "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/readme.md"
    click REQ "https://github.com/joberthcastro/ia-diagnostico-pneumonia/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef process fill:#90EE90,stroke:#333,stroke-width:1px
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px
    classDef eval fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px
```
