# timdgn/kidney_stones_classification architecture

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

- Interactive diagram: https://gitdiagram.com/timdgn/kidney_stones_classification
- Repository: https://github.com/timdgn/kidney_stones_classification

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized ML web application for kidney-stone classification.
- Frontend: Streamlit UI for user input.
- Backend: FastAPI service serving prediction requests against an XGBoost model.
- CI/CD & MLOps: AWS CodePipeline → CodeBuild → ECR → CodeDeploy → ECS Fargate → Load Balancer.

##### File Structure
- Top-level:
- `Streamlit_Frontend/` – Streamlit app, Dockerfile, requirements.
- `FastAPI_Backend/` – FastAPI app, model artifact, data, EDA scripts, Dockerfile, requirements.
- `docker-compose.yml` & `docker-compose-prod.yml` – local vs. prod orchestration.
- `buildspec.yml` – AWS CodeBuild instructions.
- Tests: `tests/test_xgb_predict.py`.
- Infra as code & config present in root manifests and compose files.

##### Extract Architecture Insights from README
- Two Docker images (frontend & backend).
- AWS pipeline triggers on GitHub push.
- CodeBuild builds images and pushes to ECR.
- CodeDeploy deploys to ECS Fargate.
- Application Load Balancer fronts the services, with an Elastic IP.

a. Main Components
- User’s Browser / Client
- Streamlit Frontend Service
- FastAPI Backend Service
- ML Model artifact (XGBoost `.pkl`)
- Docker Registry (AWS ECR)
- CI/CD Pipeline (AWS CodePipeline / CodeBuild / CodeDeploy)
- Container Cluster (AWS ECS Fargate)
- Application Load Balancer & Elastic IP
- (Optional) Data store for training data (S3 bucket or local CSV)

b. Relationships & Interactions
- Client → HTTP → Streamlit Container
- Streamlit → HTTP (REST) → FastAPI Container
- FastAPI loads ML model from local volume (or S3) and serves predictions
- GitHub → CodePipeline triggers
- CodePipeline → CodeBuild builds Docker images → pushes to ECR
- CodePipeline → CodeDeploy instructs ECS to pull new images
- ALB routes external traffic to Streamlit &/or FastAPI tasks behind ECS

c. Architectural Patterns & Principles
- Micro-service separation (frontend vs backend)
- Container-based deployment with immutable images
- CI/CD pipeline implementing GitOps
- Load-balanced, auto-scaled container tasks (Fargate)

d. Key Technologies & Frameworks
- Python, FastAPI, Streamlit, XGBoost
- Docker, docker-compose
- AWS ECR, ECS Fargate, CodePipeline, CodeBuild, CodeDeploy, ALB, Elastic IP

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    subgraph "User"
        Browser["User Browser"]:::user
    end

    %% AWS Cloud Boundary
    subgraph "AWS VPC / Account"
        direction TB

        ALB["Application Load Balancer\n(Elastic IP)"]:::external
        subgraph "ECS Fargate Cluster"
            direction TB
            Streamlit_Service["Streamlit App\n(Container)"]:::user
            FastAPI_Service["FastAPI API\n(Container)"]:::backend
            XGB_Model["XGBoost Model\n(.pkl)"]:::storage
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GitHub["GitHub Repo"]:::external
        CodePipeline["AWS CodePipeline"]:::ci
        CodeBuild["AWS CodeBuild"]:::ci
        ECR["AWS ECR"]:::external
        CodeDeploy["AWS CodeDeploy"]:::ci
    end

    %% Local & Prod Orchestration
    subgraph "Docker Compose"
        direction TB
        DockerComposeLocal["docker-compose.yml"]:::external
        DockerComposeProd["docker-compose-prod.yml"]:::external
    end

    %% Offline Data & Reports
    subgraph "Training Data & EDA"
        direction TB
        Train_Data["train.csv"]:::storage
        EDA_Script["eda_reports.py"]:::external
        Confusion_Matrix["confusion_matrix"]:::external
        ROC_AUC["roc_auc"]:::external
    end

    %% Testing & Buildspec
    TestSuite["tests/test_xgb_predict.py"]:::external
    BuildSpec["buildspec.yml"]:::external
    RootReq["requirements.txt"]:::external

    %% Data Flows
    Browser -->|"HTTP 8501"| ALB
    ALB -->|"Routes 8501"| Streamlit_Service
    Streamlit_Service -->|"REST 8000"| FastAPI_Service
    FastAPI_Service -->|"Loads Model"| XGB_Model

    %% CI/CD Flows
    GitHub -->|Push Trigger| CodePipeline
    CodePipeline -->|Start Build| CodeBuild
    CodeBuild -->|Push Images| ECR
    CodePipeline -->|Deploy| CodeDeploy
    CodeDeploy -->|Update Tasks| ECS_Fargate["ECS Fargate Cluster"]
    ECR -->|Pull Images| ECS_Fargate

    %% Orchestration (for dev/prod)
    DockerComposeLocal -.-> Streamlit_Service
    DockerComposeLocal -.-> FastAPI_Service
    DockerComposeProd -.-> Streamlit_Service
    DockerComposeProd -.-> FastAPI_Service

    %% Offline Data & Reports linkage
    EDA_Script --> Train_Data
    EDA_Script --> Confusion_Matrix
    EDA_Script --> ROC_AUC

    %% Testing and Buildspec
    CodeBuild -->|Runs Tests| TestSuite
    CodeBuild -->|Uses| BuildSpec
    BuildSpec -->|Specifies| DockerComposeProd
    BuildSpec -->|References| RootReq

    %% Styling
    classDef user fill:#cfe2ff,stroke:#0275d8;
    classDef backend fill:#d1e7dd,stroke:#198754;
    classDef ci fill:#ffedd5,stroke:#fd7e14;
    classDef external fill:#e2e3e5,stroke:#6c757d;
    classDef storage fill:#f8d7da,stroke:#d63384,shape:cylinder;

    %% Click Events
    click Streamlit_Service "https://github.com/timdgn/kidney_stones_classification/tree/main/Streamlit_Frontend/"
    click FastAPI_Service "https://github.com/timdgn/kidney_stones_classification/tree/main/FastAPI_Backend/"
    click XGB_Model "https://github.com/timdgn/kidney_stones_classification/blob/main/FastAPI_Backend/models/xgb_model_2023-06-10_00-10-25.pkl"
    click Train_Data "https://github.com/timdgn/kidney_stones_classification/blob/main/FastAPI_Backend/data/train.csv"
    click EDA_Script "https://github.com/timdgn/kidney_stones_classification/blob/main/FastAPI_Backend/src/eda_reports.py"
    click Confusion_Matrix "https://github.com/timdgn/kidney_stones_classification/tree/main/FastAPI_Backend/docs/confusion_matrix"
    click ROC_AUC "https://github.com/timdgn/kidney_stones_classification/tree/main/FastAPI_Backend/docs/roc_auc"
    click DockerComposeLocal "https://github.com/timdgn/kidney_stones_classification/blob/main/docker-compose.yml"
    click DockerComposeProd "https://github.com/timdgn/kidney_stones_classification/blob/main/docker-compose-prod.yml"
    click BuildSpec "https://github.com/timdgn/kidney_stones_classification/blob/main/buildspec.yml"
    click TestSuite "https://github.com/timdgn/kidney_stones_classification/blob/main/tests/test_xgb_predict.py"
    click RootReq "https://github.com/timdgn/kidney_stones_classification/blob/main/requirements.txt"
```
