# irangareddy/plate-planner-api architecture

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

- Interactive diagram: https://gitdiagram.com/irangareddy/plate-planner-api
- Repository: https://github.com/irangareddy/plate-planner-api

## Overview

##### Project Type and Purpose
- Plate Planner is a backend-focused, graph-powered, ML-enhanced meal assistant exposing a REST API.
- It uses FastAPI/Uvicorn to serve endpoints, Neo4j to store a recipe/ingredient graph, and FAISS + SentenceTransformers for sentence embedding and semantic search.
- Key use cases: recipe suggestion, context-aware ingredient substitution, graph bootstrap from CSV, and evaluation/analytics on the graph.

##### File Structure
- src/api          → FastAPI application entrypoint and route definitions
- src/config       → Application configuration (paths, URIs, secrets)
- src/database     → ETL-style graph-loading scripts (CSV → Neo4j edges/nodes)
- src/pipelines    → Data-processing & model-training pipelines (raw recipes → preprocessed data → FAISS index, vectors)
- src/services     → Domain services (Neo4jService for graph queries)
- src/utils        → Helper modules (ingredient normalization, vector search, dataset readers)
- src/evaluation   → Graph diagnostics, coverage audits, substitution evaluation
- src/main.py      → Top-level script to launch the API or run tasks
- Dockerfile, docker-compose.yml, Taskfile.yml → Orchestration of containers and dev tasks

##### README for Additional Insights
- “bootstrap” step that loads CSVs and pre-trained embeddings into Neo4j.

a. Main Components
- **Clients/Users**: CLI or Web UI (invoking HTTP requests, e.g., via Swagger docs).
- **FastAPI Service** (Uvicorn container):
- API routers (src/api/app.py)
- Request/response models (src/models)
- **Application Layer**:
- Config module (src/config)
- Service layer (src/services/neo4j_service.py)
- Utilities (src/utils) for normalization and vector operations
- **ML Inference**:
- SentenceTransformer model
- FAISS index lookup (src/utils/search_faiss_by_title.py)
- **Graph Database**: Neo4j instance (Docker container)
- Nodes: Ingredients, Recipes
- Relationships: SIMILAR_TO, SUBSTITUTES_WITH
- **Data Pipelines & Bootstrap**:
- Raw recipe CSV ingestion (src/pipelines/parse_raw_recipes.py)
- Embedding/training pipelines (src/pipelines/train_faiss_substitution_model.py)
- Graph load scripts (src/database/*.py)
- **Evaluation & Reporting**: Diagnostic scripts and audit tools (src/evaluation)

b. Relationships & Data Flow
- Clients → (HTTP REST) → FastAPI Service
- FastAPI Service → (Bolt/HTTP) → Neo4j Graph
- FastAPI Service → ML Inference → FAISS + SentenceTransformer → back to Service → Response
- ETL Pipelines → CSV/Vector artifacts → Graph Bootstrap → Neo4j (periodic or on-demand via `task neo4j:bootstrap`)
- Evaluation modules → Neo4j & ML artifacts → JSON/HTML reports

c. Architectural Patterns & Principles
- Layered architecture (API layer, service layer, data layer, ML layer)
- Single responsibility per module (separate pipelines, services, utils)
- Configuration isolation via `src/config`
- Containerization for reproducibility (Docker Compose orchestrates FastAPI + Neo4j)

d. Technologies & Frameworks
- Python 3.11, FastAPI + Uvicorn, Neo4j (Bolt/HTTP)
- FAISS for vector search, SentenceTransformers for embeddings
- Poetry for dependency management, Taskfile for dev tasks
- Docker Compose for multi-container orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Clients["CLI / Web UI"]:::client
    end

    %% Runtime API Layer
    subgraph "Runtime API" 
        direction TB
        API["FastAPI Service"]:::api
        Config["Configuration Module"]:::config
        Service["Neo4jService"]:::service
        NormUtils["Ingredient Normalization Utilities"]:::util
        API -->|uses| Config
        API -->|calls| Service
        Service -->|queries| Graph
        API -->|calls| MLInference
        Service -->|uses| NormUtils
    end

    %% ML Inference Layer
    subgraph "ML Inference" 
        direction TB
        EmbeddingModel["SentenceTransformer Model"]:::ml
        FAISS["FAISS Index"]:::ml
        MLInference["ML Inference"]:::ml
        MLInference -->|loads| EmbeddingModel
        MLInference -->|searches| FAISS
        EmbeddingModel --> FAISS
    end

    %% Graph Database Layer
    subgraph "Graph Database" 
        direction TB
        Graph[(Neo4j Graph)]:::db
    end

    %% Ingestion & Bootstrap Layer
    subgraph "Ingestion & Bootstrap" 
        direction TB
        Pipelines["Data Pipelines"]:::pipeline
        DBScripts["Graph Bootstrap & ETL"]:::db
        Pipelines -->|produce CSV / Vectors| DBScripts
        DBScripts -->|load into| Graph
    end

    %% Evaluation & Reporting Layer
    subgraph "Evaluation & Reporting" 
        direction TB
        EvalScripts["Evaluation Modules"]:::evaluation
        EvalScripts -->|reads| Graph
        EvalScripts -->|reads| FAISS
    end

    %% Orchestration Layer
    subgraph "Orchestration" 
        direction TB
        DockerCompose["Docker Compose"]:::orchestration
        Taskfile["Taskfile / CLI"]:::orchestration
        DockerCompose -->|orchestrates| API
        DockerCompose -->|orchestrates| Graph
        Taskfile -->|triggers| Pipelines
        Taskfile -->|triggers| DBScripts
    end

    %% Client Interaction
    Clients -->|HTTP REST| API

    %% Mermaid Click Events
    click API "https://github.com/irangareddy/plate-planner-api/blob/main/src/api/app.py"
    click Config "https://github.com/irangareddy/plate-planner-api/blob/main/src/config/config.py"
    click Config "https://github.com/irangareddy/plate-planner-api/blob/main/src/config/paths.py"
    click Config "https://github.com/irangareddy/plate-planner-api/blob/main/src/config/substitution_config.py"
    click Service "https://github.com/irangareddy/plate-planner-api/blob/main/src/services/neo4j_service.py"
    click NormUtils "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/ingredient_normalizer.py"
    click NormUtils "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/normalizer_config.yaml"
    click NormUtils "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/update_normalizer_blacklist.py"
    click EmbeddingModel "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/model_pipeline.py"
    click FAISS "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/search_faiss_by_title.py"
    click MLInference "https://github.com/irangareddy/plate-planner-api/blob/main/src/utils/recipesuggestionmodel.py"
    click DBScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/database/bootstrap_graph.py"
    click DBScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/database/load_into_neo4j.py"
    click DBScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/database/add_edges_from_csv.py"
    click DBScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/database/build_similar_to_edges.py"
    click DBScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/database/upload_recipe_metadata.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/parse_raw_recipes.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/train_faiss_substitution_model.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/build_context_vectors.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/extract_cooking_verbs.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/split_dataset.py"
    click Pipelines "https://github.com/irangareddy/plate-planner-api/blob/main/src/pipelines/add_substitutes_with_edges.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/graph_diagnostics.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/coverage_audit.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/diagnose_targets.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/filter_edges.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/hybrid_substitution.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/random_subs.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/ranx_suggest_recipes.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/run_substitution_queries.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/suggest_substitutes.py"
    click EvalScripts "https://github.com/irangareddy/plate-planner-api/blob/main/src/evaluation/substitution_eval_results.json"
    click Taskfile "https://github.com/irangareddy/plate-planner-api/blob/main/Taskfile.yml"
    click DockerCompose "https://github.com/irangareddy/plate-planner-api/blob/main/docker-compose.yml"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef config fill:#ccf,stroke:#333,stroke-width:1px
    classDef service fill:#bfb,stroke:#333,stroke-width:1px
    classDef util fill:#dfd,stroke:#333,stroke-width:1px
    classDef ml fill:#fbf,stroke:#333,stroke-width:1px
    classDef db fill:#ffd,stroke:#333,stroke-width:1px,shape:cylinder
    classDef pipeline fill:#ffb,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef evaluation fill:#fdd,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
