# lucasocp/ifood-smart-ingestion-agent architecture

> Architecture diagram of the GitHub repository lucasocp/ifood-smart-ingestion-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasocp/ifood-smart-ingestion-agent
- Repository: https://github.com/lucasocp/ifood-smart-ingestion-agent

## Overview

This is an iFood menu-ingestion and semantic-search service. Its main workflow collects menu records and reviews, derives review sentiment, normalizes menu data and infers dietary and allergen attributes, then indexes enriched items for filtered similarity search. The FastAPI layer triggers ingestion and serves search results; the index is in memory and rebuilt at startup. The graph follows the README and shown source excerpts; unsampled implementation details are not assumed.

Main entry points: [`src/pipeline.py`](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/pipeline.py) (Ingestion and Search Pipeline), [`app.py`](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/app.py) (FastAPI REST API), [`src/models.py`](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/models.py) (Data Contracts), [`src/scraper/async_scraper.py`](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/scraper/async_scraper.py) (Menu Scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Service API"]
  node_api["FastAPI REST API<br/>[app.py]"]
  node_pipeline["Ingestion and Search Pipeline<br/>[pipeline.py]"]
end

subgraph group_ingestion["Catalog Ingestion"]
  node_scraper["Menu Scraper<br/>[async_scraper.py]"]
end

subgraph group_enrichment["Enrichment"]
  node_sentiment["Review Sentiment"]
  node_normalizer["Schema Normalizer"]
  node_contracts["Data Contracts<br/>[models.py]"]
  node_compat["Model Compatibility<br/>[compat.py]"]
end

subgraph group_retrieval["Semantic Retrieval"]
  node_indexer["Vector Indexer<br/>[vector_indexer.py]"]
  node_catalog[("In-Memory Catalog<br/>[vector_indexer.py]")]
end

node_consumer(("User / iFood App"))
node_raw_catalog["Menus and Reviews"]

node_consumer -->|"submits requests"| node_api
node_raw_catalog -->|"provides catalog data"| node_scraper
node_api -->|"triggers ingestion"| node_pipeline
node_api -->|"requests search"| node_pipeline
node_pipeline -->|"fetches records"| node_scraper
node_scraper -->|"creates raw items"| node_contracts
node_pipeline -->|"analyzes reviews"| node_sentiment
node_pipeline -->|"normalizes items"| node_normalizer
node_normalizer -->|"creates enriched items"| node_contracts
node_sentiment -->|"returns sentiment summary"| node_contracts
node_pipeline -->|"indexes items"| node_indexer
node_pipeline -->|"delegates search"| node_indexer
node_indexer -->|"stores and searches"| node_catalog
node_contracts -->|"uses model base"| node_compat
node_api -->|"returns results"| node_consumer

click node_api "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/app.py"
click node_pipeline "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/pipeline.py"
click node_scraper "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/scraper/async_scraper.py"
click node_sentiment "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/agents/review_sentiment_agent.py"
click node_normalizer "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/agents/schema_normalizer.py"
click node_contracts "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/models.py"
click node_compat "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/compat.py"
click node_indexer "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/vector_store/vector_indexer.py"
click node_catalog "https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/vector_store/vector_indexer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_pipeline,node_consumer,node_raw_catalog toneBlue
class node_scraper toneAmber
class node_sentiment,node_normalizer,node_contracts,node_compat toneMint
class node_indexer,node_catalog toneRose
```

## Components

### Service API

- [FastAPI REST API](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/app.py): `app.py`
- [Ingestion and Search Pipeline](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/pipeline.py): `src/pipeline.py`

### Catalog Ingestion

- [Menu Scraper](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/scraper/async_scraper.py): `src/scraper/async_scraper.py`

### Enrichment

- [Review Sentiment](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/agents/review_sentiment_agent.py): `src/agents/review_sentiment_agent.py`
- [Schema Normalizer](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/agents/schema_normalizer.py): `src/agents/schema_normalizer.py`
- [Data Contracts](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/models.py): `src/models.py`
- [Model Compatibility](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/compat.py): `src/compat.py`

### Semantic Retrieval

- [Vector Indexer](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/vector_store/vector_indexer.py): `src/vector_store/vector_indexer.py`
- [In-Memory Catalog](https://github.com/lucasocp/ifood-smart-ingestion-agent/blob/main/src/vector_store/vector_indexer.py): `src/vector_store/vector_indexer.py`

### Other components

- **User / iFood App**
- **Menus and Reviews**

## Connections

- User / iFood App → FastAPI REST API: submits requests (evidence: `README.md`)
- Menus and Reviews → Menu Scraper: provides catalog data (evidence: `README.md`)
- FastAPI REST API → Ingestion and Search Pipeline: triggers ingestion (evidence: `app.py`)
- FastAPI REST API → Ingestion and Search Pipeline: requests search (evidence: `app.py`)
- Ingestion and Search Pipeline → Menu Scraper: fetches records (evidence: `src/pipeline.py`)
- Menu Scraper → Data Contracts: creates raw items (evidence: `src/scraper/async_scraper.py`)
- Ingestion and Search Pipeline → Review Sentiment: analyzes reviews (evidence: `src/pipeline.py`)
- Ingestion and Search Pipeline → Schema Normalizer: normalizes items (evidence: `src/pipeline.py`)
- Schema Normalizer → Data Contracts: creates enriched items (evidence: `src/agents/schema_normalizer.py`)
- Review Sentiment → Data Contracts: returns sentiment summary (evidence: `src/agents/review_sentiment_agent.py`)
- Ingestion and Search Pipeline → Vector Indexer: indexes items (evidence: `src/pipeline.py`)
- Ingestion and Search Pipeline → Vector Indexer: delegates search (evidence: `src/pipeline.py`)
- Vector Indexer → In-Memory Catalog: stores and searches (evidence: `src/vector_store/vector_indexer.py`)
- Data Contracts → Model Compatibility: uses model base (evidence: `src/models.py`)
- FastAPI REST API → User / iFood App: returns results (evidence: `app.py`)