# jhackisneros/vision_artificial architecture

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

- Interactive diagram: https://gitdiagram.com/jhackisneros/vision_artificial
- Repository: https://github.com/jhackisneros/vision_artificial

## Overview

##### Project Type and Purpose
- This is an end-to-end machine learning system with two major facets:
a) An ML research and experimentation pipeline (data preprocessing, model training, hyperparameter tuning, evaluation, explainability, robustness testing, pruning/quantization, ensemble methods).
b) A deployed inference service (a Flask-based web application packaged in Docker with user authentication via Firebase).
- The goal is to build, evaluate and optimize CNN/MLP models for a computer-vision task (likely image classification), produce lightweight TFLite models, and host a user-facing dashboard that serves real-time predictions.

##### File Structure Analysis
- Top-level directories:
- notebooks/    → Jupyter notebooks illustrating each stage of the ML workflow.
- experiments/  → JSON/CSV artifacts from hyperparameter trials, ensemble results, robustness scores.
- models/       → Trained model artifacts: .keras, .tflite, and ensemble sub-models.
- src/          → Production-quality Python modules: data ingestion, model definitions, training, evaluation, tuning, explainability, robustness, pruning/quantization, utilities.
- scripts/      → Automation entry-points: converting to TFLite, exporting metrics, initializing Firebase, orchestrating full training runs.
- deployment/   → Dockerfile + Flask app: REST endpoints, static assets (HTML, CSS, JS), Firebase config, utility modules for auth, prediction, theming.
- Configuration:
- requirements.txt & deployment/flask_app/requirements-deploy.txt for dependency management.
- deployment/run_flask.sh to launch the service in container.

##### Key Components
A. Data Layer
- Raw dataset (images + labels) → src/data.py → persists to local/remote storage.
B. Preprocessing & Augmentation
- Notebook “02_preprocessing” & src/module(s) handle resizing, normalization, augmentation (18 configurations in notebooks).
C. Model Training & Tuning
- src/model_cnn.py / model_mlp.py define architectures.
- src/train.py launches training loops.
- src/tuning.py & hyperparam_trials.json drive Bayesian/grid search.
D. Model Evaluation & Analysis
- src/evaluate.py, src/robustness.py, src/explainability.py produce metrics, GradCAM heatmaps.
- experiments/*.json, *.csv store results.
E. Model Optimization
- src/pruning_quant.py applies pruning and quantization.
- scripts/convert_to_tflite.py exports .tflite.
F. Ensemble Construction
- src/ensemble.py builds ensemble from multiple .keras sub-models.
G. Artifact Storage
- models/ directory holds final .keras, .tflite, ensemble models.
H. Deployment Service
- Docker container running Flask app (deployment/flask_app/app.py).
- Loads TFLite or Keras model at startup.
- Exposes endpoints for user login, registration, prediction, profile, password reset.
- UI templates (HTML/CSS/JS) for dashboard, notifications, theming.
- Firebase for user authentication and data persistence.
I. Automation Scripts
- scripts/reproduce_experiment.sh & run_all_training.sh orchestrate full pipelines.

##### Relationships & Data Flows
- Data Layer → Preprocessing → Training/Tuning → Evaluation → Optimization → Model Artifacts.
- Artifacts → Deployment Service (via volume mount or image build).
- Deployment Service ↔ Firebase (auth & user data).
- Frontend (browser) ↔ Flask API (prediction requests, user management).
- Optionally, scripts can trigger end-to-end workflows and populate the experiments folder.

##### Architectural Patterns & Design Principles
- Modular separation of concerns: src modules strictly separated by functionality (data, model, evaluation, utils).
- Reproducibility: deterministic scripts, config file (src/utils/config.py), experiment logs.
- Layered architecture for the web app: Templates, Static assets, Business logic (Flask views), Utilities (auth, prediction).
- ML/DevOps convergence: clear boundary between research notebooks and production code.

##### Technologies & Frameworks
- Python 3.x, TensorFlow/Keras, TensorFlow Lite, Flask, Docker, Firebase (Auth & Firestore), Jupyter, shell scripting.
- Logging & config via JSON (experiments), Python modules (src/utils/config.py).

## Diagram (Mermaid)

```mermaid
graph TD
    %% ML Pipeline Stages
    DL["Data Layer"]:::mlPipeline
    PP["Preprocessing & Augmentation"]:::mlPipeline
    Train["Training & Hyperparameter Tuning"]:::mlPipeline
    Eval["Model Evaluation & Analysis"]:::mlPipeline
    Opt["Model Optimization"]:::mlPipeline
    Ens["Ensemble Construction"]:::mlPipeline
    Store["Artifact Storage"]:::mlPipeline

    %% Deployment Service
    subgraph "Deployment Service (Flask + Docker)"
        Docker["Docker Setup"]:::production
        App["Flask App"]:::production
        FirebaseConfig["Firebase Config"]:::production
        Static["Static Assets"]:::production
        Templates["HTML Templates"]:::production
        Utils["Web Utilities"]:::production
    end

    %% External Services
    Browser["Browser Client"]:::external
    FirebaseService["Firebase Auth & Firestore"]:::external

    %% Automation Scripts
    Scripts["Automation Scripts"]:::scripts

    %% Flow Connections
    DL -->|"images, labels"| PP
    PP -->|"preprocessed data"| Train
    Train -->|"checkpoints, hyperparam logs"| Eval
    Eval -->|"metrics, heatmaps"| Opt
    Opt -->|"pruned & quantized models"| Ens
    Ens -->|"ensemble checkpoints"| Store
    Store -->|"mount models"| App
    Docker -->|"runs container"| App
    Browser -->|"HTTP/JSON"| App
    App -->|"Auth & Data"| FirebaseService
    Scripts -->|"trigger pipeline"| Train
    Scripts -->|"deploy setup"| App

    %% Click Events for ML Pipeline
    click DL "https://github.com/jhackisneros/vision_artificial/blob/main/src/data.py"
    click PP "https://github.com/jhackisneros/vision_artificial/blob/main/notebooks/02_preprocessing.ipynb"
    click Train "https://github.com/jhackisneros/vision_artificial/blob/main/src/train.py"
    click Train "https://github.com/jhackisneros/vision_artificial/blob/main/src/tuning.py"
    click Train "https://github.com/jhackisneros/vision_artificial/blob/main/experiments/hyperparam_trials.json"
    click Eval "https://github.com/jhackisneros/vision_artificial/blob/main/src/evaluate.py"
    click Eval "https://github.com/jhackisneros/vision_artificial/blob/main/src/robustness.py"
    click Eval "https://github.com/jhackisneros/vision_artificial/blob/main/src/explainability.py"
    click Eval "https://github.com/jhackisneros/vision_artificial/blob/main/experiments/robustness_scores.csv"
    click Eval "https://github.com/jhackisneros/vision_artificial/blob/main/notebooks/12_explainability_gradcam.ipynb"
    click Opt "https://github.com/jhackisneros/vision_artificial/blob/main/src/pruning_quant.py"
    click Opt "https://github.com/jhackisneros/vision_artificial/blob/main/scripts/convert_to_tflite.py"
    click Opt "https://github.com/jhackisneros/vision_artificial/blob/main/models/cnn_pruned.tflite"
    click Ens "https://github.com/jhackisneros/vision_artificial/blob/main/src/ensemble.py"
    click Ens "https://github.com/jhackisneros/vision_artificial/tree/main/models/ensemble/"
    click Store "https://github.com/jhackisneros/vision_artificial/blob/main/models/*.keras"
    click Store "https://github.com/jhackisneros/vision_artificial/blob/main/models/*.tflite"
    click Store "https://github.com/jhackisneros/vision_artificial/tree/main/models/ensemble/"

    %% Click Events for Deployment
    click Docker "https://github.com/jhackisneros/vision_artificial/tree/main/deployment/Dockerfile"
    click Docker "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/run_flask.sh"
    click App "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/flask_app/app.py"
    click FirebaseConfig "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/flask_app/firebase_config.json"
    click Static "https://github.com/jhackisneros/vision_artificial/tree/main/deployment/flask_app/static/css/"
    click Static "https://github.com/jhackisneros/vision_artificial/tree/main/deployment/flask_app/static/js/"
    click Templates "https://github.com/jhackisneros/vision_artificial/tree/main/deployment/flask_app/templates/"
    click Utils "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/flask_app/utils/auth_utils.py"
    click Utils "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/flask_app/utils/prediction_utils.py"
    click Utils "https://github.com/jhackisneros/vision_artificial/blob/main/deployment/flask_app/utils/theme_utils.py"

    %% Click Events for Scripts
    click Scripts "https://github.com/jhackisneros/vision_artificial/blob/main/scripts/run_all_training.sh"
    click Scripts "https://github.com/jhackisneros/vision_artificial/blob/main/scripts/reproduce_experiment.sh"
    click Scripts "https://github.com/jhackisneros/vision_artificial/blob/main/scripts/init_firebase.py"
    click Scripts "https://github.com/jhackisneros/vision_artificial/blob/main/scripts/export_metrics.py"

    %% Styles
    classDef mlPipeline fill:#cce5ff,stroke:#2196f3,color:#000;
    classDef production fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#fff3cd,stroke:#ff9800,color:#000;
    classDef scripts fill:#f0f0f0,stroke:#6c757d,color:#000;
```
