# zinhlemm/track-my-impact architecture

> Architecture diagram of the GitHub repository zinhlemm/track-my-impact, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zinhlemm/track-my-impact
- Repository: https://github.com/zinhlemm/track-my-impact

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page web application (built with Streamlit) that leverages a pre-trained Convolutional Neural Network (Keras) to classify household waste images and compute the environmental impact (CO₂, water, energy savings) of correct disposal.

##### High­-Level Components
a. Streamlit Frontend
- The UI layer in `waste_classifier/classify.py` and Streamlit app code that handles user image upload and displays results.
b. Classification Engine (Backend)
- Core logic in `waste_classifier/classifier.py` plus model files (`waste_model.keras`, `classnames.json`).
- Prediction pipeline: load model → preprocess image → infer class → return label and confidence.
c. Impact Calculator
- Reads `data/emission_factors.json` to map predicted class to environmental savings.
- Business logic lives alongside the classifier or as part of the same module.
d. Data Storage
- Raw and processed datasets under `dataset/` and `dataset/split/` (train/val/test) for training and testing.
- Model artifacts in `waste_classifier/model/`.
- Static lookup files (`data/emission_factors.json`).
e. Preprocessing & Training Scripts
- `scripts/split_dataset.py` for dataset partitioning.
- `waste_classifier/train_waste_classifier.py` to train or fine-tune the CNN.
f. Dependencies & Deployment
- `requirements.txt` lists Streamlit, TensorFlow/Keras, PIL/OpenCV, etc.
- No external microservices—this is a self-contained Python app.

##### Relationships & Data Flow
1. User uploads image in the Streamlit UI.
2. Frontend sends the image to the Classification Engine.
3. Engine loads the `.keras` model and classnames, preprocesses the image, and outputs a class prediction.
4. Impact Calculator module looks up emission factors in `emission_factors.json`.
5. Combined results (class + CO₂/water/energy savings) return to the UI for display.
6. (Optional for training) Data preprocessing scripts feed into the Training Script, outputting an updated model artifact.

##### Architectural Patterns & Design Principles
- MVC-style separation:
- View = Streamlit UI
- Controller = classification & calculation logic
- Model = serialized Keras model + data artifacts
- Single-process monolith using Python modules
- Clear separation of concerns: data (JSON, dataset folders), model (Keras), UI (Streamlit), scripts (preprocessing & training)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI)"
        UI["Streamlit UI\nwaste_classifier/classify.py"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        subgraph "Classification Engine"
            Classifier["Classifier Logic\nwaste_classifier/classifier.py"]:::compute
            ModelArtifact["Pre-trained Model\nwaste_classifier/model/waste_model.keras"]:::storage
            ClassNames["Class Names\nwaste_classifier/model/classnames.json"]:::storage
        end
        subgraph "Impact Calculator"
            ImpactCalc["Impact Calculator Logic"]:::compute
            EmissionJSON["Emission Factors\ndata/emission_factors.json"]:::storage
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        Dataset["Raw & Processed Dataset\ndataset/"]:::storage
        SplitDirs["Dataset Splits\ndataset/split/"]:::storage
        ResultsLog["Classifier Results Log\nclassifier_results.json"]:::storage
        RunCommands["Run Commands Reference\ndata/run_commands.txt"]:::storage
        Requirements["Project Dependencies\nrequirements.txt"]:::storage
        Docs["Project Documentation\nREADME.md"]:::doc
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        RawData["Dataset\ndataset/"]:::storage
        Preprocess["Preprocessing Script\nscripts/split_dataset.py"]:::scripts
        TrainScript["Training Script\nwaste_classifier/train_waste_classifier.py"]:::scripts
    end

    %% Data Flow
    UI -->|"uploads image"| Classifier
    Classifier -->|"loads model"| ModelArtifact
    Classifier -->|"loads classnames"| ClassNames
    Classifier -->|"predicts label"| ImpactCalc
    ImpactCalc -->|"looks up factors"| EmissionJSON
    ImpactCalc -->|"returns results"| UI

    %% Training Flow
    RawData --> Preprocess --> TrainScript --> ModelArtifact

    %% Click Events
    click UI "https://github.com/zinhlemm/track-my-impact/blob/main/waste_classifier/classify.py"
    click Classifier "https://github.com/zinhlemm/track-my-impact/blob/main/waste_classifier/classifier.py"
    click ModelArtifact "https://github.com/zinhlemm/track-my-impact/blob/main/waste_classifier/model/waste_model.keras"
    click ClassNames "https://github.com/zinhlemm/track-my-impact/blob/main/waste_classifier/model/classnames.json"
    click EmissionJSON "https://github.com/zinhlemm/track-my-impact/blob/main/data/emission_factors.json"
    click Dataset "https://github.com/zinhlemm/track-my-impact/tree/main/dataset/"
    click SplitDirs "https://github.com/zinhlemm/track-my-impact/tree/main/dataset/split/"
    click Preprocess "https://github.com/zinhlemm/track-my-impact/blob/main/scripts/split_dataset.py"
    click TrainScript "https://github.com/zinhlemm/track-my-impact/blob/main/waste_classifier/train_waste_classifier.py"
    click ResultsLog "https://github.com/zinhlemm/track-my-impact/blob/main/classifier_results.json"
    click RunCommands "https://github.com/zinhlemm/track-my-impact/blob/main/data/run_commands.txt"
    click Requirements "https://github.com/zinhlemm/track-my-impact/blob/main/requirements.txt"
    click Docs "https://github.com/zinhlemm/track-my-impact/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#1f77b4,color:#000
    classDef compute fill:#D0FFD0,stroke:#2ca02c,color:#000
    classDef storage fill:#FFFACD,stroke:#bcbd22,color:#000
    classDef scripts fill:#FFE4B5,stroke:#ff7f0e,color:#000
    classDef doc fill:#E0E0E0,stroke:#7f7f7f,color:#000
```
