# pathway-platform/menu-parser architecture

> Architecture diagram of the GitHub repository pathway-platform/menu-parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pathway-platform/menu-parser
- Repository: https://github.com/pathway-platform/menu-parser

## Overview

menu-parser is a FastAPI service that turns restaurant menu URLs into persisted menu items, generated recipes and canonical ingredient rollups, then USDA-backed price and trend snapshots. Its main user workflow is three API operations: parse a menu, generate recipes from stored menu items, and retrieve ingredient pricing. A separate discovery command builds the ingredient-to-USDA report mapping used by pricing. The graph reflects the sampled route orchestration and service behavior; discovery-to-pricing mapping use is documented in the README.

Main entry points: [`app/api/routes.py`](https://github.com/pathway-platform/menu-parser/blob/main/app/api/routes.py) (API routes), [`scripts/usda_discovery.py`](https://github.com/pathway-platform/menu-parser/blob/main/scripts/usda_discovery.py) (USDA report discovery), [`app/services/pricing.py`](https://github.com/pathway-platform/menu-parser/blob/main/app/services/pricing.py) (Pricing and trend computation), [`app/services/recipe.py`](https://github.com/pathway-platform/menu-parser/blob/main/app/services/recipe.py) (Recipe and ingredient generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_menu["Menu extraction"]
  node_scraper["Browser scraper<br/>[scraper.py]"]
  node_html["Rendered menu HTML<br/>[scraper.py]"]
  node_extractor["Menu item extractor<br/>[extractor.py]"]
end

subgraph group_recipes["Recipes and ingredients"]
  node_recipe_service["Recipe and ingredient generation<br/>[recipe.py]"]
end

subgraph group_pricing["Pricing and discovery"]
  node_pricing_service["Pricing and trend computation<br/>[pricing.py]"]
  node_mapping["USDA ingredient mapping<br/>[pricing.py]"]
  node_discovery["USDA report discovery<br/>[usda_discovery.py]"]
  node_keywords["Ingredient keywords"]
end

subgraph group_data["Persistence"]
  node_menu_storage["Menu item storage<br/>[storage.py]"]
  node_ingredients[("Ingredients and recipes")]
  node_postgres[("Postgres database")]
end

node_restaurant(("Restaurant menu site"))
node_client(("API client"))
node_openai{{"OpenAI API"}}
node_usda{{"USDA AMS Market News"}}

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_routes
node_routes -->|"uses schemas"| node_schemas
node_routes -->|"renders URL"| node_scraper
node_restaurant -->|"serves page"| node_scraper
node_scraper -->|"saves HTML"| node_html
node_routes -->|"extracts items"| node_extractor
node_extractor -->|"queries model"| node_openai
node_routes -->|"saves items"| node_menu_storage
node_menu_storage -->|"writes menu items"| node_postgres
node_routes -->|"generates recipes"| node_recipe_service
node_recipe_service -->|"generates and normalizes"| node_openai
node_recipe_service -->|"reads menu, writes rollups"| node_postgres
node_routes -->|"computes pricing"| node_pricing_service
node_pricing_service -->|"reads ingredients, saves snapshot"| node_postgres
node_pricing_service -->|"loads mapping"| node_mapping
node_pricing_service -->|"fetches price series"| node_usda
node_discovery -->|"reads ingredients"| node_postgres
node_discovery -->|"loads keywords"| node_keywords
node_discovery -->|"samples reports"| node_usda
node_discovery -->|"writes mapping"| node_mapping

click node_app "https://github.com/pathway-platform/menu-parser/blob/main/app/main.py"
click node_routes "https://github.com/pathway-platform/menu-parser/blob/main/app/api/routes.py"
click node_schemas "https://github.com/pathway-platform/menu-parser/blob/main/app/schemas.py"
click node_scraper "https://github.com/pathway-platform/menu-parser/blob/main/app/services/scraper.py"
click node_html "https://github.com/pathway-platform/menu-parser/blob/main/app/services/scraper.py"
click node_extractor "https://github.com/pathway-platform/menu-parser/blob/main/app/services/extractor.py"
click node_menu_storage "https://github.com/pathway-platform/menu-parser/blob/main/app/services/storage.py"
click node_recipe_service "https://github.com/pathway-platform/menu-parser/blob/main/app/services/recipe.py"
click node_pricing_service "https://github.com/pathway-platform/menu-parser/blob/main/app/services/pricing.py"
click node_mapping "https://github.com/pathway-platform/menu-parser/blob/main/app/services/pricing.py"
click node_discovery "https://github.com/pathway-platform/menu-parser/blob/main/scripts/usda_discovery.py"
click node_keywords "https://github.com/pathway-platform/menu-parser/blob/main/ingredient_keywords.yaml"

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_app,node_routes,node_schemas,node_client toneBlue
class node_scraper,node_html,node_extractor toneAmber
class node_recipe_service,node_openai toneMint
class node_pricing_service,node_mapping,node_discovery,node_keywords toneRose
class node_menu_storage,node_ingredients,node_postgres,node_restaurant,node_usda toneIndigo
```

## Components

### HTTP API

- [FastAPI application](https://github.com/pathway-platform/menu-parser/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/pathway-platform/menu-parser/blob/main/app/api/routes.py): `app/api/routes.py`
- [Request and response schemas](https://github.com/pathway-platform/menu-parser/blob/main/app/schemas.py): `app/schemas.py`

### Menu extraction

- [Browser scraper](https://github.com/pathway-platform/menu-parser/blob/main/app/services/scraper.py): `app/services/scraper.py`
- [Rendered menu HTML](https://github.com/pathway-platform/menu-parser/blob/main/app/services/scraper.py): `app/services/scraper.py`
- [Menu item extractor](https://github.com/pathway-platform/menu-parser/blob/main/app/services/extractor.py): `app/services/extractor.py`

### Recipes and ingredients

- [Recipe and ingredient generation](https://github.com/pathway-platform/menu-parser/blob/main/app/services/recipe.py): `app/services/recipe.py`

### Pricing and discovery

- [Pricing and trend computation](https://github.com/pathway-platform/menu-parser/blob/main/app/services/pricing.py): `app/services/pricing.py`
- [USDA ingredient mapping](https://github.com/pathway-platform/menu-parser/blob/main/app/services/pricing.py): `app/services/pricing.py`
- [USDA report discovery](https://github.com/pathway-platform/menu-parser/blob/main/scripts/usda_discovery.py): `scripts/usda_discovery.py`
- [Ingredient keywords](https://github.com/pathway-platform/menu-parser/blob/main/ingredient_keywords.yaml): `ingredient_keywords.yaml`

### Persistence

- [Menu item storage](https://github.com/pathway-platform/menu-parser/blob/main/app/services/storage.py): `app/services/storage.py`
- **Ingredients and recipes**
- **Postgres database**

### Other components

- **Restaurant menu site**
- **API client**
- **OpenAI API**
- **USDA AMS Market News**

## Connections

- API client → FastAPI application: sends requests (evidence: `README.md`)
- FastAPI application → API routes: registers routes (evidence: `app/main.py`)
- API routes → Request and response schemas: uses schemas (evidence: `app/api/routes.py`)
- API routes → Browser scraper: renders URL (evidence: `app/api/routes.py`)
- Restaurant menu site → Browser scraper: serves page (evidence: `app/services/scraper.py`)
- Browser scraper → Rendered menu HTML: saves HTML (evidence: `app/services/scraper.py`)
- API routes → Menu item extractor: extracts items (evidence: `app/api/routes.py`)
- Menu item extractor → OpenAI API: queries model (evidence: `app/services/extractor.py`)
- API routes → Menu item storage: saves items (evidence: `app/api/routes.py`)
- Menu item storage → Postgres database: writes menu items (evidence: `app/services/storage.py`)
- API routes → Recipe and ingredient generation: generates recipes (evidence: `app/api/routes.py`)
- Recipe and ingredient generation → OpenAI API: generates and normalizes (evidence: `app/services/recipe.py`)
- Recipe and ingredient generation → Postgres database: reads menu, writes rollups (evidence: `app/services/recipe.py`)
- API routes → Pricing and trend computation: computes pricing (evidence: `app/api/routes.py`)
- Pricing and trend computation → Postgres database: reads ingredients, saves snapshot (evidence: `app/services/pricing.py`)
- Pricing and trend computation → USDA ingredient mapping: loads mapping (evidence: `README.md`)
- Pricing and trend computation → USDA AMS Market News: fetches price series (evidence: `app/services/pricing.py`)
- USDA report discovery → Postgres database: reads ingredients (evidence: `README.md`)
- USDA report discovery → Ingredient keywords: loads keywords (evidence: `scripts/usda_discovery.py`)
- USDA report discovery → USDA AMS Market News: samples reports (evidence: `scripts/usda_discovery.py`)
- USDA report discovery → USDA ingredient mapping: writes mapping (evidence: `README.md`)
