# nigh7wind/gemma4-grocery-agent architecture

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

- Interactive diagram: https://gitdiagram.com/nigh7wind/gemma4-grocery-agent
- Repository: https://github.com/nigh7wind/gemma4-grocery-agent

## Overview

Grocery Agent turns a photo of a handwritten list into a reviewed Instamart cart: the PWA uploads the image, the backend extracts structured items, the user confirms or edits them, and deterministic catalog resolution presents ambiguous choices. The backend then builds and diffs the cart for display and handoff to Swiggy. The graph also preserves the preference store, session state, token handling, and both product-picking interfaces. README documents some capabilities not visible in the excerpts; those links are omitted where their caller is not evidenced.

Main entry points: [`app/main.py`](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/main.py) (FastAPI routes), [`frontend/src/App.jsx`](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/App.jsx) (App workflow), [`frontend/src/api.js`](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/api.js) (REST and SSE client), [`frontend/src/components/ListConfirmScreen.jsx`](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ListConfirmScreen.jsx) (List review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA client"]
  node_app_ui["App workflow<br/>[App.jsx]"]
  node_api_client["REST and SSE client<br/>[api.js]"]
  node_list_review["List review"]
  node_swipe_deck["Swipe deck<br/>[SwipeDeck.jsx]"]
  node_swipe_card["Swipe card<br/>[SwipeCard.jsx]"]
  node_list_item["List item card<br/>[ListItemCard.jsx]"]
  node_product_swipe["Product swipe picker"]
  node_product_grid["Product grid picker"]
  node_product_card["Product card<br/>[ProductCard.jsx]"]
end

subgraph group_service["Backend service"]
  node_backend["FastAPI routes<br/>[main.py]"]
  node_session_state[("Checkout session state<br/>[sessions.py]")]
  node_contracts["Data contracts<br/>[schemas.py]"]
  node_vision["List extraction<br/>[vision.py]"]
end

subgraph group_matching["Catalog matching"]
  node_resolver["Product resolution<br/>[resolution.py]"]
  node_preferences[("Preference memory<br/>[preferences.py]")]
end

subgraph group_integrations["External systems"]
  node_mcp_client["Swiggy MCP client<br/>[mcp_client.py]"]
  node_token_store[("OAuth token store<br/>[token_store.py]")]
end

node_shopper(("Shopper"))
node_llm["Local vision LLM"]
node_swiggy["Swiggy Instamart"]
node_native_app["Swiggy app"]

node_shopper -->|"uses"| node_app_ui
node_app_ui -->|"calls"| node_api_client
node_list_review -->|"edits list"| node_api_client
node_product_swipe -->|"submits choices"| node_api_client
node_product_grid -->|"submits choices"| node_api_client
node_list_review -->|"renders"| node_swipe_deck
node_swipe_deck -->|"renders"| node_swipe_card
node_list_review -->|"renders"| node_list_item
node_product_swipe -->|"renders"| node_swipe_deck
node_product_swipe -->|"renders"| node_product_card
node_app_ui -->|"shows"| node_list_review
node_app_ui -->|"shows"| node_product_swipe
node_app_ui -->|"shows"| node_product_grid
node_api_client -->|"HTTP and SSE"| node_backend
node_backend -->|"reads and updates"| node_session_state
node_backend -->|"extracts photo"| node_vision
node_backend -->|"resolves items"| node_resolver
node_backend -->|"builds cart"| node_mcp_client
node_backend -->|"uses token state"| node_token_store
node_backend -->|"uses requests"| node_contracts
node_vision -->|"invokes"| node_llm
node_resolver -->|"checks preferences"| node_preferences
node_resolver -->|"searches inventory"| node_mcp_client
node_mcp_client -->|"calls MCP tools"| node_swiggy
node_backend -.->|"hands off cart"| node_native_app
node_swiggy -.->|"opens checkout"| node_native_app

click node_app_ui "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/api.js"
click node_list_review "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ListConfirmScreen.jsx"
click node_swipe_deck "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/SwipeDeck.jsx"
click node_swipe_card "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/SwipeCard.jsx"
click node_list_item "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ListItemCard.jsx"
click node_product_swipe "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductDecisionScreen.jsx"
click node_product_grid "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductGridScreen.jsx"
click node_product_card "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductCard.jsx"
click node_backend "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/main.py"
click node_session_state "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/sessions.py"
click node_contracts "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/schemas.py"
click node_vision "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/vision.py"
click node_resolver "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/resolution.py"
click node_preferences "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/preferences.py"
click node_mcp_client "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/mcp_client.py"
click node_token_store "https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/token_store.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_app_ui,node_api_client,node_list_review,node_swipe_deck,node_swipe_card,node_list_item,node_product_swipe,node_product_grid,node_product_card toneBlue
class node_backend,node_session_state,node_contracts,node_vision toneAmber
class node_resolver,node_preferences toneMint
class node_mcp_client,node_token_store toneRose
class node_shopper,node_llm,node_swiggy,node_native_app toneIndigo
```

## Components

### PWA client

- [App workflow](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [REST and SSE client](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [List review](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ListConfirmScreen.jsx): `frontend/src/components/ListConfirmScreen.jsx`
- [Swipe deck](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/SwipeDeck.jsx): `frontend/src/components/SwipeDeck.jsx`
- [Swipe card](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/SwipeCard.jsx): `frontend/src/components/SwipeCard.jsx`
- [List item card](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ListItemCard.jsx): `frontend/src/components/ListItemCard.jsx`
- [Product swipe picker](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductDecisionScreen.jsx): `frontend/src/components/ProductDecisionScreen.jsx`
- [Product grid picker](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductGridScreen.jsx): `frontend/src/components/ProductGridScreen.jsx`
- [Product card](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/frontend/src/components/ProductCard.jsx): `frontend/src/components/ProductCard.jsx`

### Backend service

- [FastAPI routes](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/main.py): `app/main.py`
- [Checkout session state](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/sessions.py): `app/sessions.py`
- [Data contracts](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/schemas.py): `app/schemas.py`
- [List extraction](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/vision.py): `app/vision.py`

### Catalog matching

- [Product resolution](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/resolution.py): `app/resolution.py`
- [Preference memory](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/preferences.py): `app/preferences.py`

### External systems

- [Swiggy MCP client](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/mcp_client.py): `app/mcp_client.py`
- [OAuth token store](https://github.com/nigh7wind/gemma4-grocery-agent/blob/main/app/token_store.py): `app/token_store.py`

### Other components

- **Shopper**
- **Local vision LLM**
- **Swiggy Instamart**
- **Swiggy app**

## Connections

- Shopper → App workflow: uses (evidence: `README.md`)
- App workflow → REST and SSE client: calls (evidence: `frontend/src/App.jsx`)
- List review → REST and SSE client: edits list (evidence: `frontend/src/components/ListConfirmScreen.jsx`)
- Product swipe picker → REST and SSE client: submits choices (evidence: `frontend/src/components/ProductDecisionScreen.jsx`)
- Product grid picker → REST and SSE client: submits choices (evidence: `frontend/src/components/ProductGridScreen.jsx`)
- List review → Swipe deck: renders (evidence: `frontend/src/components/ListConfirmScreen.jsx`)
- Swipe deck → Swipe card: renders (evidence: `frontend/src/components/SwipeDeck.jsx`)
- List review → List item card: renders (evidence: `frontend/src/components/ListConfirmScreen.jsx`)
- Product swipe picker → Swipe deck: renders (evidence: `frontend/src/components/ProductDecisionScreen.jsx`)
- Product swipe picker → Product card: renders (evidence: `frontend/src/components/ProductDecisionScreen.jsx`)
- App workflow → List review: shows (evidence: `frontend/src/App.jsx`)
- App workflow → Product swipe picker: shows (evidence: `frontend/src/App.jsx`)
- App workflow → Product grid picker: shows (evidence: `frontend/src/App.jsx`)
- REST and SSE client → FastAPI routes: HTTP and SSE (evidence: `README.md`)
- FastAPI routes → Checkout session state: reads and updates (evidence: `app/main.py`)
- FastAPI routes → List extraction: extracts photo (evidence: `app/main.py`)
- FastAPI routes → Product resolution: resolves items (evidence: `app/main.py`)
- FastAPI routes → Swiggy MCP client: builds cart (evidence: `app/main.py`)
- FastAPI routes → OAuth token store: uses token state (evidence: `app/main.py`)
- FastAPI routes → Data contracts: uses requests (evidence: `app/main.py`)
- List extraction → Local vision LLM: invokes (evidence: `app/vision.py`)
- Product resolution → Preference memory: checks preferences (evidence: `app/resolution.py`)
- Product resolution → Swiggy MCP client: searches inventory (evidence: `app/resolution.py`)
- Swiggy MCP client → Swiggy Instamart: calls MCP tools (evidence: `app/mcp_client.py`)
- FastAPI routes → Swiggy app: hands off cart (evidence: `README.md`)
- Swiggy Instamart → Swiggy app: opens checkout (evidence: `README.md`)
