# mwasifanwar/culinaryai architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/culinaryai
- Repository: https://github.com/mwasifanwar/culinaryai

## Overview

##### Project Type and Purpose
- culinaryai is a backend‐focused AI service (a Python “monolith” organized into clear modules) that offers:
- Recipe generation (text and image‐to‐recipe)
- Flavor prediction and pairing
- Food chemistry analysis & nutrition calculation
- It exposes its functionality via an API layer (src/api/server.py) and is configured by config.yaml.

##### File‐Structure → Architectural Components
- src/api/
- server.py – REST (or HTTP) endpoints; the “entry point” for all external requests.
- src/data_processing/
- recipe_parser.py, molecular_processor.py, flavor_analyzer.py – preprocess and extract structured data from raw recipe text or molecular data.
- src/food_science/
- chemistry_analyzer.py, nutrition_calculator.py, pairing_engine.py – core domain logic for molecular gastronomy, nutrition, and flavor pairings.
- src/generative_models/
- flavor_predictor.py, recipe_generator.py, image_to_recipe.py – inference wrappers around trained ML/DL models that generate text or predict flavor profiles.
- src/multi_modal/
- cross_modal_encoder.py, fusion_model.py – components to fuse image and text representations for multi‐modal inference.
- src/utils/
- config.py – loads config.yaml; helpers.py – shared utility functions.
- main.py – bootstraps the server (loads config, initializes modules, starts listening).

##### Key Architectural Patterns
- Modular decomposition: each domain area (API, data processing, food science, generative models, multi-modal) lives in its own namespace.
- Pipeline pattern: requests flow through preprocessing → domain logic → model inference → postprocessing.
- Inversion of Control: central server orchestrates sub‐modules rather than having modules call each other implicitly.
- Configuration‐driven: behavior and model paths are injected via config.yaml and config.py.

##### Components & Interactions
a. External Clients
- Web/mobile UI or CLI → HTTP/JSON → src/api/server.py
b. API Layer (src/api)
- Receives request, authenticates/validates → routes to one of four pipelines:
– Data‐Processing Pipeline
– Food‐Science Pipeline
– Generative‐Model Pipeline
– Multi‐Modal Pipeline
c. Data‐Processing Module
- recipe_parser → molecular_processor → flavor_analyzer
- Outputs structured data (ingredients, molecular features)
d. Food‐Science Module
- chemistry_analyzer ↔ nutrition_calculator ↔ pairing_engine
- Consumes structured data or raw input
e. Generative‐Models Module
- recipe_generator → flavor_predictor → image_to_recipe
- Uses model checkpoints loaded via config
f. Multi‐Modal Module
- cross_modal_encoder → fusion_model
- Takes image bytes + text; returns fused embeddings for downstream generative or analysis tasks
g. Utilities & Config
- config.py provides global settings to all modules
- helpers.py supplies common routines (logging, data formatting)

##### Relationships & Data Flow
- Within each pipeline, directional flow: preprocessing → domain logic → model inference → response builder
- Shared utils and config as lateral dependencies injected into each module
- (Optionally) a model‐registry or filesystem block for “Model Checkpoints” accessed by generative_models and multi_modal

##### Technologies & External Services
- Python 3.x, FastAPI or Flask (in server.py), PyTorch or TensorFlow for ML models, YAML for config
- Potential external storage: S3 or local disk for model artifacts
- (If present) a database for caching results or telemetry

##### Final Checklist
[ ] Main components boxed & labeled
[ ] External dependencies: Clients, Model Store, Config
[ ] Clear indication of module interactions (e.g., generative_models ↔ multi_modal)
[ ] Footnote explaining pipeline patterns and modular organization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Clients<br/>(Web/Mobile/CLI)"]:::external

    %% Entry Point
    Bootstrap["Application Bootstrap<br/>(main.py)"]:::api

    %% API Layer
    API["API Layer<br/>(src/api/server.py)"]:::api

    %% Pipelines
    subgraph "Data-Processing Pipeline"
        direction TB
        DP1["Recipe Parser"]:::dp
        DP2["Molecular Processor"]:::dp
        DP3["Flavor Analyzer"]:::dp
    end

    subgraph "Food-Science Pipeline"
        direction TB
        FS1["Chemistry Analyzer"]:::domain
        FS2["Nutrition Calculator"]:::domain
        FS3["Pairing Engine"]:::domain
    end

    subgraph "Generative-Models Pipeline"
        direction TB
        GM1["Recipe Generator"]:::ml
        GM2["Flavor Predictor"]:::ml
        GM3["Image-to-Recipe"]:::ml
    end

    subgraph "Multi-Modal Pipeline"
        direction TB
        MM1["Cross-Modal Encoder"]:::ml
        MM2["Fusion Model"]:::ml
    end

    %% Utilities & Config
    subgraph "Utilities & Configuration"
        direction TB
        Config["Config Loader"]:::util
        Helpers["Helpers"]:::util
        ConfigFile["Configuration File<br/>(config.yaml)"]:::util
        ModelStore["Model Checkpoints"]:::external
    end

    %% Data Flow
    Client -->|"HTTP/JSON"| API
    Bootstrap --> API
    API -->|"to Data-Processing"| DP1
    API -->|"to Food-Science"| FS1
    API -->|"to Generative-Models"| GM1
    API -->|"to Multi-Modal"| MM1

    %% Data-Processing Flow
    DP1 -->|"parsed data"| DP2
    DP2 -->|"features"| DP3
    DP3 -->|"structured data"| API

    %% Food-Science Flow
    FS1 -->|"analysis results"| FS2
    FS2 -->|"nutrition data"| FS3
    FS3 -->|"pairing suggestions"| API

    %% Generative-Models Flow
    GM1 -->|"recipe text"| GM2
    GM2 -->|"flavor profile"| GM3
    GM3 -->|"generated recipe"| API

    %% Multi-Modal Flow
    MM1 -->|"embeddings"| MM2
    MM2 -->|"fused embeddings"| API

    %% Utilities & Config usage
    ConfigFile --> Config
    Config --> API
    Config --> DP1
    Config --> FS1
    Config --> GM1
    Config --> MM1
    Helpers --> API
    Helpers --> DP2
    Helpers --> FS2
    Helpers --> GM2
    Helpers --> MM2
    ModelStore --> GM1
    ModelStore --> MM1

    %% Click Events
    click API "https://github.com/mwasifanwar/culinaryai/blob/main/src/api/server.py"
    click DP1 "https://github.com/mwasifanwar/culinaryai/blob/main/src/data_processing/recipe_parser.py"
    click DP2 "https://github.com/mwasifanwar/culinaryai/blob/main/src/data_processing/molecular_processor.py"
    click DP3 "https://github.com/mwasifanwar/culinaryai/blob/main/src/data_processing/flavor_analyzer.py"
    click FS1 "https://github.com/mwasifanwar/culinaryai/blob/main/src/food_science/chemistry_analyzer.py"
    click FS2 "https://github.com/mwasifanwar/culinaryai/blob/main/src/food_science/nutrition_calculator.py"
    click FS3 "https://github.com/mwasifanwar/culinaryai/blob/main/src/food_science/pairing_engine.py"
    click GM1 "https://github.com/mwasifanwar/culinaryai/blob/main/src/generative_models/recipe_generator.py"
    click GM2 "https://github.com/mwasifanwar/culinaryai/blob/main/src/generative_models/flavor_predictor.py"
    click GM3 "https://github.com/mwasifanwar/culinaryai/blob/main/src/generative_models/image_to_recipe.py"
    click MM1 "https://github.com/mwasifanwar/culinaryai/blob/main/src/multi_modal/cross_modal_encoder.py"
    click MM2 "https://github.com/mwasifanwar/culinaryai/blob/main/src/multi_modal/fusion_model.py"
    click Config "https://github.com/mwasifanwar/culinaryai/blob/main/src/utils/config.py"
    click Helpers "https://github.com/mwasifanwar/culinaryai/blob/main/src/utils/helpers.py"
    click Bootstrap "https://github.com/mwasifanwar/culinaryai/blob/main/main.py"
    click ConfigFile "https://github.com/mwasifanwar/culinaryai/blob/main/config.yaml"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef dp fill:#E0F8E0,stroke:#333,stroke-width:1px;
    classDef domain fill:#C8FACC,stroke:#333,stroke-width:1px;
    classDef ml fill:#FFE8B0,stroke:#333,stroke-width:1px;
    classDef util fill:#F0F0F0,stroke:#333,stroke-width:1px;
    classDef external fill:#F8E0E0,stroke:#333,stroke-width:1px;
```
