# ae-ai-hit15/cats-vs-dogs-image-classification architecture

> Architecture diagram of the GitHub repository ae-ai-hit15/cats-vs-dogs-image-classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ae-ai-hit15/cats-vs-dogs-image-classification
- Repository: https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification

## Overview

##### Project Type and Purpose
- This is a full-stack image classification system that uses a deep learning (CNN) model to differentiate between images of cats and dogs.
- The project has two distinct parts: a backend that handles model inference and an API (using FastAPI) and a frontend (built with Streamlit) for user interaction.
- In addition, there’s an offline training pipeline contained in the “model_train_data” directory along with utility scripts for organizing and retraining the model.

##### File Structure
- Top-level files:
- “app.py” (Streamlit frontend) and “main.py” (possibly used for API/backend; note that the README also refers to a “main_app.py”, so be sure to capture the intent of having both a UI and an API service).
- “organize_train_data.py” and “retrain_model.py” imply tasks related to organizing the training data and updating the model.
- “requirements.txt” and “.gitignore” which are standard auxiliary files.
- “model_train_data” directory: Contains the core training pipeline components including:
- data_preprocessing.py (handling image preprocessing)
- model_building.py (defining the architecture)
- training scripts (train.py and training.py)
- evaluation.py (model evaluation)
- visualization.py (plotting accuracy/loss curves)
- The README further clarifies that external directories exist (like data/ and models/) even though they are not part of the file tree provided. They represent datasets and the stored H5 model files respectively.

a. Main Components to Include:
- User Interface (Frontend): Represented by Streamlit (app.py); the user uploads images for prediction.
- API / Backend Service: Built with FastAPI (likely represented by main.py or main_app.py); this layer receives requests from the UI and interfaces with the model.
- Model Inference & Prediction Module: This is where the trained deep learning model (.h5 file) is loaded and executed. It depends on TensorFlow.
- Training Pipeline: This contains modules for pre-processing, model building, training, evaluation, and visualization – all found in the “model_train_data” directory. Also include scripts like “organize_train_data.py” and “retrain_model.py” as parts of the model lifecycle.
- Data Storage: While not explicitly part of the codebase, note that the architecture integrates with external data (images in train, validation, and test directories) as well as persisted model files stored in a “models/” directory.

b. Relationships and Interactions:
- The user uses the Frontend (Streamlit) to upload an image.
- The image is sent to the Backend API (FastAPI), which then loads the trained model using TensorFlow to process the image and return a prediction along with its confidence.
- The backend then sends the result back to the UI.
- Additionally, the training pipeline (illustrated as a separate flow) handles data preprocessing -> model building -> training -> evaluation -> visualization. This component is used offline to produce the final .h5 model used at runtime.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The system is clearly divided between the model training lifecycle and the runtime inference framework (frontend and backend).
- Modular Design: Each script/module handles a specific task (for example, “data_preprocessing.py” handles preprocessing, “visualization.py” handles graphing metrics, etc.).
- API-Driven Interaction: Use of FastAPI and Streamlit ensures a clear API boundary between the client and the server.
- Reusability & Extensibility: With separate scripts for organizing data and retraining the model, the system can be easily updated or extended with new features (like new image formats).

d. Technologies and Frameworks:
- Python as the core language.
- TensorFlow for model construction and inference.
- FastAPI combined with Uvicorn for the backend API.
- Streamlit for the frontend user interface.
- Standard Python libraries (as indicated by the requirements.txt file) for filtering, visualization, and other scripting tasks.

##### Essential Elements to be Included
- Use clear labels for each component (e.g., Frontend: Streamlit UI, Backend: FastAPI API, Model Inference, Training Pipeline, Data Storage).
- From User → Frontend → API → Model Inference → API → Frontend → User.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Operations
    subgraph "Runtime Operations"
        U("User")
        UI("Streamlit UI")
        API("FastAPI API")
        INF("Model Inference Engine")
    end

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        ORG("Organize Training Data")
        DP("Data Preprocessing")
        MB("Model Building")
        T1("Training Script (train.py)")
        T2("Training Script (trainning.py)")
        EV("Model Evaluation")
        VIS("Visualization")
        RET("Model Retraining")
        DS("Data Storage (Data)")
        MS("Model Storage (Models)")
    end

    %% Runtime Flow
    U -->|"upload_image"| UI
    UI -->|"send_request"| API
    API -->|"process_request"| INF
    INF -->|"return_result"| API
    API -->|"display_result"| UI
    UI -->|"feedback"| U

    %% Training Pipeline Flow
    DS --- ORG
    ORG -->|"organize_data"| DP
    DP -->|"preprocess_images"| MB
    MB -->|"build_model"| T1
    T1 -->|"train_model"| T2
    T2 -->|"evaluate"| EV
    EV -->|"visualize_metrics"| VIS
    VIS -->|"trigger_retrain"| RET
    RET -->|"update_model"| MS

    %% Click Events for Runtime Components
    click UI "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/app.py"
    click API "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/main.py"
    click INF "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/main.py"

    %% Click Events for Training Pipeline Components
    click DP "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/data_preprocessing.py"
    click MB "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/model_building.py"
    click T1 "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/train.py"
    click T2 "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/trainning.py"
    click EV "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/evaluation.py"
    click VIS "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/model_train_data/visualization.py"
    click ORG "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/organize_train_data.py"
    click RET "https://github.com/ae-ai-hit15/cats-vs-dogs-image-classification/blob/main/retrain_model.py"

    %% Styling
    class UI frontend
    class API backend
    class INF inference
    class ORG,DP,MB,T1,T2,EV,VIS,RET training
    class DS,MS external

    %% Class Definitions
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef inference fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef training fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
