# abijith-vs/fridge-ammachi architecture

> Architecture diagram of the GitHub repository abijith-vs/fridge-ammachi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abijith-vs/fridge-ammachi
- Repository: https://github.com/abijith-vs/fridge-ammachi

## Overview

##### What this project is (type + purpose)
**Fridge_Whisperer Ammachi** is a **small full-stack web app**:
- **Frontend:** static **HTML/CSS/JS** in `/static` (UI, mood selection, animations, speech bubbles).
- **Backend:** **Python FastAPI** (`main.py`) served by **Uvicorn**.
- **AI/ML inference:** **YOLOv8 (PyTorch)** for ingredient detection (`yolov8m.pt`) + an additional **grocery classifier** (Keras `.h5` + MobileNet runner) under `/classifier`.
- **Business logic:** “recipe suggestion” generation in `recipe_gen.py` based on detected ingredients.
- **Supporting scripts:** image preprocessing (`image_procc.py`), entrypoints (`run.py`, `main.py`).

##### How to read the file tree into architectural components
Use the tree to split into **runtime containers** vs **offline tooling**:

##### Runtime (what runs when user uses the app)
- **Frontend (static site)**
- `static/index.html`
- `static/style.css`
- `static/fallingVeggies.js`
- **Backend API (FastAPI)**
- `main.py` (FastAPI app; likely defines endpoints for upload / ingredient input / recipe response)
- `run.py` (helper to start/serve)
- **Image + ML inference pipeline**
- `image_procc.py` (image loading, resizing, normalization, etc. via Pillow)
- `yolov8m.pt` (YOLO model weights)
- `classifier/predict.py` (inference wrapper for grocery classifier)
- `classifier/model/grocery_classifier.h5`
- `classifier/model/classes.txt`
- `classifier/model/run_mobilenet.py` (MobileNet-based inference runner)
- **Recipe generation**
- `recipe_gen.py` (turn ingredients into recipe suggestions / text)

##### Offline / development workflows (don’t confuse with runtime)
- `classifier/train_classify.py` (training pipeline)
- `classifier/train/*` (training image dataset by category: curd/juice/milk/sauce)
- `requirements.txt` (runtime dependencies)
- `.env` (config; can imply API keys, env toggles, etc.)

##### Static Frontend (HTML/CSS/JS)
- Runs in browser
- Handles: mood selection UI, upload form, animations, rendering results
##### ML Inference Module (YOLOv8 + Grocery Classifier)
- YOLOv8 weights: `yolov8m.pt`
- Keras classifier: `grocery_classifier.h5`
##### Recipe Generator (recipe_gen.py)
- Converts ingredient list → recipe suggestions + “Ammachi” dialogue text

Data stores:
- There’s **no explicit database** in the tree. Represent storage as:
- **In-memory** processing (default)
- Optional “local temp files” if upload is saved (unknown—call it out as assumption)

Inside “Backend API,” show components mapped to files:
- `main.py` → **API Router / Controllers**
- `image_procc.py` → **Image Preprocessor**
- YOLO wrapper (wherever implemented; likely in `main.py` or helper) → **Object Detection Service**
- `classifier/predict.py` → **Grocery Classification Service**
- `recipe_gen.py` → **Recipe + Dialogue Generator**

At least two flows:

**Flow 1: Image upload**
##### Browser: renders recipe + mood-based Ammachi speech

**Flow 2: Manual ingredients**
##### FastAPI → Browser: recipes + dialogue

- **Local dev:** Browser + Uvicorn on localhost + models on local filesystem
- **Hosted (HF Spaces):** Browser → HF Spaces app container (FastAPI) → model files in container image/storage

- **Browser → FastAPI**
- Protocol: HTTP (JSON + multipart file upload)
- **FastAPI → Image preprocessing**
- Library: Pillow (per README)
- **FastAPI → YOLOv8 inference**
- Library: PyTorch/Ultralytics (implied by YOLOv8)
- Artifact: `yolov8m.pt`
- **FastAPI → Grocery classifier**
- Artifact: `grocery_classifier.h5`, `classes.txt`
- This is a second-stage classifier; show it as “optional refinement” if YOLO already detects items.
- **FastAPI → Recipe generator**
- Input: ingredient list (+ mood)
- Output: recipe suggestions + text
- **FastAPI → Browser**
- Output: response payload

**offline training**:
- Training images `classifier/train/*` → `train_classify.py` → outputs `.h5` + `classes.txt`

##### Architectural patterns to highlight (based on structure)
- **Thin frontend, API-driven backend:** static UI calls FastAPI.
- **Pipeline architecture for inference:** preprocess → detect → (optional classify/refine) → generate recipe.
- **Separation of concerns by file/module:** API entry (`main.py`), CV (`image_procc.py` + model weights), classification (`classifier/`), recipe logic (`recipe_gen.py`).
- **Offline training vs online inference separation:** `/classifier/train_*` vs `/classifier/predict.py`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (C4 L1)
    %% =========================
    subgraph "System Context (C4 L1)"
        U["User (Browser)"]:::external

        subgraph "Fridge Whisperer Ammachi (Web App)"
            SYS_FE["Static Web UI (HTML/CSS/JS)"]:::frontend
            SYS_BE["FastAPI Backend API (Uvicorn)"]:::backend
            SYS_ML["ML Inference (YOLOv8 + Grocery Classifier)"]:::ml
            SYS_REC["Recipe + Dialogue Generator"]:::logic
        end

        HF["Hugging Face Spaces (optional deployment)"]:::external
    end

    U -->|"HTTP(S)"| SYS_FE
    SYS_FE -->|"HTTP (JSON + multipart/form-data)"| SYS_BE
    SYS_BE -->|"calls"| SYS_ML
    SYS_BE -->|"calls"| SYS_REC
    SYS_BE -->|"JSON response (ingredients,recipes,dialogue)"| SYS_FE

    HF -.->|"hosts (optional)"| SYS_BE

    %% =========================
    %% Container Diagram (C4 L2)
    %% =========================
    subgraph "Container Diagram (C4 L2) - Runtime"
        direction TB

        subgraph "Browser (Client)"
            direction TB
            FE_ROOT["Static Frontend"]:::frontend
            FE_UI["Upload + Mood Selection + Results Rendering UI"]:::frontend
            FE_STYLE["CSS Styling"]:::frontend
            FE_ANIM["Falling Veggies Animation"]:::frontend
        end

        subgraph "Backend (Server)"
            direction TB
            BE_API["FastAPI App + Routes"]:::backend
            BE_RUN["Uvicorn Runner / Entrypoint"]:::backend
            BE_PIPE["Inference + Recipe Pipeline Orchestrator"]:::backend
        end

        subgraph "ML Inference Module"
            direction TB
            PRE["Image Preprocessor (Pillow)"]:::component
            YOLO["YOLOv8 Detector (PyTorch/Ultralytics)"]:::ml
            CLS["Grocery Classifier Service (Keras/MobileNet)"]:::ml
        end

        subgraph "Business Logic"
            direction TB
            ING_NORM["Ingredient Normalization (conceptual)"]:::component
            RECIPE["Recipe Suggestion + Dialogue Generator"]:::logic
            MOOD_FMT["Mood-based Dialogue Formatter (conceptual)"]:::logic
        end

        subgraph "Model Artifacts (loaded at runtime)"
            direction TB
            W_YOLO[("yolov8m.pt")]:::artifact
            W_H5[("grocery_classifier.h5")]:::artifact
            W_CLASSES[("classes.txt")]:::artifact
        end

        subgraph "Configuration"
            direction TB
            ENV[".env (secrets/toggles)"]:::config
            REQS["requirements.txt (deps)"]:::config
        end
    end

    %% Frontend internals
    FE_ROOT -->|"contains"| FE_UI
    FE_ROOT -->|"contains"| FE_STYLE
    FE_ROOT -->|"contains"| FE_ANIM

    %% Client -> Server (two input modes)
    FE_UI -->|"POST image (multipart/form-data) + mood"| BE_API
    FE_UI -->|"POST ingredients (JSON) + mood"| BE_API

    %% Backend runtime wiring
    BE_RUN -->|"starts"| BE_API
    BE_API -->|"orchestrates"| BE_PIPE
    BE_API -->|"reads env"| ENV

    %% Pipeline steps
    BE_PIPE -->|"preprocess image"| PRE
    PRE -->|"tensor/array"| YOLO
    YOLO -->|"detected labels list"| ING_NORM
    YOLO -.->|"optional refine/categorize"| CLS
    CLS -.->|"refined labels"| ING_NORM

    ING_NORM -->|"ingredient list + mood"| RECIPE
    RECIPE -->|"recipe candidates"| MOOD_FMT
    MOOD_FMT -->|"dialogue + recipes + ingredients"| BE_API
    BE_API -->|"JSON payload"| FE_UI

    %% Model artifact loading
    YOLO -->|"loads weights"| W_YOLO
    CLS -->|"loads weights"| W_H5
    CLS -->|"loads labels"| W_CLASSES

    %% =========================
    %% Component Diagram (C4 L3) - Backend internals mapped to files
    %% =========================
    subgraph "Component Diagram (C4 L3) - Backend (FastAPI)"
        direction TB

        API_CTRL["API Router / Controllers (upload + ingredients)"]:::backend
        ORCH["Request Orchestrator / Pipeline Coordinator"]:::backend

        IMGPROC["Image Preprocessing Module"]:::component
        DETECT["Object Detection Service (YOLOv8)"]:::ml
        CLASSIFY["Grocery Classification Service"]:::ml
        RECGEN["Recipe + Dialogue Generator"]:::logic

        MOBRUN["MobileNet Runner Helper"]:::ml

        API_CTRL -->|"calls"| ORCH
        ORCH -->|"calls"| IMGPROC
        ORCH -->|"calls"| DETECT
        ORCH -.->|"optional"| CLASSIFY
        ORCH -->|"calls"| RECGEN

        CLASSIFY -->|"uses"| MOBRUN

        DETECT -->|"loads"| W_YOLO
        CLASSIFY -->|"loads"| W_H5
        CLASSIFY -->|"loads"| W_CLASSES
    end

    %% =========================
    %% Offline / Model Training (separate dashed lane)
    %% =========================
    subgraph "Offline / Model Training (not runtime)"
        direction TB

        DS["Training Dataset (images by category)"]:::offline
        DS_CURD["curd/"]:::offline
        DS_JUICE["juice/"]:::offline
        DS_MILK["milk/"]:::offline
        DS_SAUCE["sauce/"]:::offline

        TRAIN["Training Pipeline (train_classify.py)"]:::offline
        OUT_H5[("grocery_classifier.h5 (trained)")]:::artifact
        OUT_CLASSES[("classes.txt (exported)")]:::artifact

        DS -->|"contains"| DS_CURD
        DS -->|"contains"| DS_JUICE
        DS -->|"contains"| DS_MILK
        DS -->|"contains"| DS_SAUCE

        DS -->|"feeds"| TRAIN
        TRAIN -->|"outputs"| OUT_H5
        TRAIN -->|"outputs"| OUT_CLASSES

        OUT_H5 -.->|"packaged for runtime"| W_H5
        OUT_CLASSES -.->|"packaged for runtime"| W_CLASSES
    end

    %% =========================
    %% Deployment (pragmatic)
    %% =========================
    subgraph "Deployment (Pragmatic)"
        direction TB

        subgraph "Local Dev"
            direction TB
            D_BROWSER["Browser"]:::external
            D_UV["Uvicorn + FastAPI (localhost)"]:::backend
            D_FS["Local filesystem (models/static)"]:::store
        end

        subgraph "Hosted (HF Spaces - optional)"
            direction TB
            H_BROWSER["Browser"]:::external
            H_CONT["HF Spaces App Container (FastAPI)"]:::backend
            H_MODELS["Container image/storage (models)"]:::store
        end

        D_BROWSER -->|"HTTP"| D_UV
        D_UV -->|"reads"| D_FS

        H_BROWSER -->|"HTTP(S)"| H_CONT
        H_CONT -->|"reads"| H_MODELS
    end

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click FE_ROOT "https://github.com/abijith-vs/fridge-ammachi/tree/main/static/"
    click FE_UI "https://github.com/abijith-vs/fridge-ammachi/blob/main/static/index.html"
    click FE_STYLE "https://github.com/abijith-vs/fridge-ammachi/blob/main/static/style.css"
    click FE_ANIM "https://github.com/abijith-vs/fridge-ammachi/blob/main/static/fallingVeggies.js"

    click BE_API "https://github.com/abijith-vs/fridge-ammachi/blob/main/main.py"
    click BE_RUN "https://github.com/abijith-vs/fridge-ammachi/blob/main/run.py"

    click PRE "https://github.com/abijith-vs/fridge-ammachi/blob/main/image_procc.py"
    click IMGPROC "https://github.com/abijith-vs/fridge-ammachi/blob/main/image_procc.py"

    click W_YOLO "https://github.com/abijith-vs/fridge-ammachi/blob/main/yolov8m.pt"

    click CLS "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/predict.py"
    click CLASSIFY "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/predict.py"

    click W_H5 "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/model/grocery_classifier.h5"
    click W_CLASSES "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/model/classes.txt"
    click MOBRUN "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/model/run_mobilenet.py"

    click RECIPE "https://github.com/abijith-vs/fridge-ammachi/blob/main/recipe_gen.py"
    click RECGEN "https://github.com/abijith-vs/fridge-ammachi/blob/main/recipe_gen.py"

    click TRAIN "https://github.com/abijith-vs/fridge-ammachi/blob/main/classifier/train_classify.py"
    click DS "https://github.com/abijith-vs/fridge-ammachi/tree/main/classifier/train/"
    click DS_CURD "https://github.com/abijith-vs/fridge-ammachi/tree/main/classifier/train/curd/"
    click DS_JUICE "https://github.com/abijith-vs/fridge-ammachi/tree/main/classifier/train/juice/"
    click DS_MILK "https://github.com/abijith-vs/fridge-ammachi/tree/main/classifier/train/milk/"
    click DS_SAUCE "https://github.com/abijith-vs/fridge-ammachi/tree/main/classifier/train/sauce/"

    click REQS "https://github.com/abijith-vs/fridge-ammachi/blob/main/requirements.txt"
    click ENV "https://github.com/abijith-vs/fridge-ammachi/blob/main/.env"

    %% =========================
    %% Styles (color is critical)
    %% =========================
    classDef external fill:#e8e8e8,stroke:#6b6b6b,color:#111,stroke-width:1px
    classDef frontend fill:#cfe8ff,stroke:#2b6cb0,color:#0b1f33,stroke-width:1px
    classDef backend fill:#b9dcff,stroke:#1d4ed8,color:#0b1f33,stroke-width:1px
    classDef component fill:#c9f7d8,stroke:#15803d,color:#0b1f33,stroke-width:1px
    classDef ml fill:#bff2c2,stroke:#166534,color:#0b1f33,stroke-width:1px
    classDef logic fill:#e3d4ff,stroke:#6d28d9,color:#1a1033,stroke-width:1px
    classDef artifact fill:#ffd8a8,stroke:#c2410c,color:#2b1304,stroke-width:1px
    classDef offline fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:2px,stroke-dasharray: 6 4
    classDef config fill:#fff3bf,stroke:#a16207,color:#1f1400,stroke-width:1px
    classDef store fill:#ffe4e6,stroke:#be123c,color:#2b0b10,stroke-width:1px
```
