How irangareddy/plate-planner-api works
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