# samadarsh/bitewise architecture

> Architecture diagram of the GitHub repository samadarsh/bitewise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samadarsh/bitewise
- Repository: https://github.com/samadarsh/bitewise

## Overview

#### 1. Purpose and deployable entry points
BiteWise is a food-intelligence platform with two bounded product modules: nutrition-aware Swiggy meal ordering (NutriOrder) and shared pantry/meal/grocery planning (SmartPantry). The backend FastAPI application starts at `backend/main.py`; the browser client is a Next.js App Router application rooted at `frontend/app/page.tsx`, with authenticated product UI at `frontend/app/app/page.tsx` and a guided demo at `frontend/app/pitch/page.tsx`.

#### 2. API composition and persistence boundary
`backend/main.py` composes route domains for users/authentication, coach/nutrition, recommendations, orders, household, pantry, grocery, and demo data. SQLAlchemy persistence is centralized through `backend/db/session.py` and `backend/db/models.py`, with SQLite/PostgreSQL-ready models. Domain-level models live beside their APIs, including `backend/household/models.py`, `backend/pantry/models.py`, and `backend/recommendations/models.py`.

#### 3. Identity, sessions, and Swiggy authorization
User authentication and session handling are separated from Swiggy delegated authorization. `backend/auth/user_auth.py` and `backend/auth/sessions.py` protect BiteWise users; `backend/auth/swiggy_oauth.py` implements OAuth 2.1 PKCE and encrypted token handling for Swiggy. `backend/auth/rate_limiter.py` forms an API-protection boundary. The frontend supplies auth state and request integration through `frontend/lib/auth-context.tsx` and `frontend/lib/api.ts`.

#### 4. NutriOrder decision pipeline
The AI/decision layer converts profile, goals, and preferences into explainable meal candidates. Core orchestration is in `agent/pipeline.py` and `agent/agent.py`; it derives nutrition targets and estimates nutrition through `agent/nutrition_targets.py` and `agent/nutrition_estimator.py`, then ranks candidates with tradeoffs such as macros, price, delivery, taste, confidence, and priorities in `agent/ranking.py`. Recommendation APIs/service expose the resulting shortlist via `backend/recommendations/service.py` and `backend/recommendations/routes.py`. Caching, memory, resilience, and observability are explicit operational layers in `agent/caching.py`, `agent/memory.py`, `agent/resilience.py`, and `agent/observability.py`.

#### 5. Food execution and safety boundary
BiteWise consumes Swiggy Food through an MCP client boundary rather than directly embedding provider calls: `backend/mcp/swiggy_client.py` and `mcp/mcp_client.py`. Mock implementations (`mcp/mcp_mock.py`, `mcp/instamart_mock.py`) support demos and local operation. Order APIs and lifecycle controls are in `backend/orders/routes.py` and `backend/orders/state_machine.py`. Execution is deliberately gated by review, explicit confirmation, environment configuration, and the order-placement lock; real Instamart checkout is excluded.

#### 6. SmartPantry household planning flow
Household membership and dietary constraints enter through `backend/household/routes.py` and are synthesized by `backend/household/service.py` / `backend/household/intelligence.py`. Pantry inventory APIs and seeded recipe templates in `backend/pantry/routes.py` and `backend/pantry/templates.py` identify stock gaps, cookable recipes, and low-stock conditions. Those gaps flow to grocery-list/category/priority generation and a mock cart preview through `backend/grocery/routes.py` and `backend/grocery/models.py`. This module plans purchases; it does not execute Instamart payment or checkout.

#### 7. Client experience, runtime, and infrastructure
The Next.js/React/TypeScript frontend presents NutriOrder dashboards and recommendation controls via `frontend/components/NutriOrderDashboard.tsx` and `frontend/components/RecommendationCard.tsx`, while SmartPantry is composed in `frontend/components/household/HouseholdDashboard.tsx` and related panels. Python/FastAPI runs the API and agent stack; Node.js runs the Next.js client. Docker deployment is represented by `Dockerfile` and `frontend/Dockerfile`; `render.yaml` supplies platform deployment configuration. Runtime behavior, provider mode, credentials, and safety switches are centralized in `config/settings.py` and `.env.example`.

Main entry points: [`backend/main.py`](https://github.com/samadarsh/bitewise/blob/main/backend/main.py) (API application), [`backend/db/session.py`](https://github.com/samadarsh/bitewise/blob/main/backend/db/session.py) (SQLAlchemy persistence), [`agent/pipeline.py`](https://github.com/samadarsh/bitewise/blob/main/agent/pipeline.py) (Decision pipeline), [`frontend/app/app/page.tsx`](https://github.com/samadarsh/bitewise/blob/main/frontend/app/app/page.tsx) (Authenticated product UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Next.js client"]
  node_public_ui["Public entry<br/>Next.js route<br/>[page.tsx]"]
  node_product_ui["Authenticated product UI<br/>Next.js route<br/>[page.tsx]"]
  node_demo_ui["Guided demo<br/>Next.js route<br/>[page.tsx]"]
  node_nutri_dashboard["NutriOrder dashboard<br/>React component"]
  node_household_dashboard["Household dashboard<br/>React component"]
  node_client_auth_api["Auth state &amp; API client<br/>frontend integration<br/>[auth-context.tsx]"]
end

subgraph group_api["FastAPI platform"]
  node_api_app{{"API application<br/>FastAPI entry point<br/>[main.py]"}}
  node_identity["User auth &amp; sessions<br/>identity boundary<br/>[user_auth.py]"]
  node_swiggy_auth["Swiggy OAuth PKCE<br/>delegated authorization<br/>[swiggy_oauth.py]"]
  node_recommendations_api["Recommendation service<br/>API service<br/>[service.py]"]
  node_orders["Order lifecycle<br/>order API<br/>[state_machine.py]"]
  node_database[("SQLAlchemy persistence<br/>SQLite/PostgreSQL<br/>[session.py]")]
end

subgraph group_decision["NutriOrder intelligence"]
  node_agent_pipeline{{"Decision pipeline<br/>agent orchestration<br/>[pipeline.py]"}}
  node_nutrition_ranking["Nutrition &amp; ranking<br/>decision engine<br/>[ranking.py]"]
  node_agent_operations["Agent operations<br/>cache, memory &amp; resilience<br/>[caching.py]"]
end

subgraph group_pantry["SmartPantry"]
  node_household_intelligence["Household intelligence<br/>planning service<br/>[intelligence.py]"]
  node_pantry_planning["Pantry &amp; recipes<br/>inventory planning<br/>[templates.py]"]
  node_grocery_planning["Grocery list &amp; cart preview<br/>grocery API<br/>[routes.py]"]
end

subgraph group_provider["Provider &amp; deployment"]
  node_swiggy_mcp["Swiggy MCP boundary<br/>provider client<br/>[swiggy_client.py]"]
  node_provider_mock["Mock provider<br/>demo provider<br/>[mcp_mock.py]"]
  node_runtime_settings["Runtime safety settings<br/>configuration boundary<br/>[settings.py]"]
  node_deployment["Docker deployment<br/>container runtime"]
end

node_public_ui -->|"enters"| node_product_ui
node_product_ui -->|"renders"| node_nutri_dashboard
node_product_ui -->|"renders"| node_household_dashboard
node_demo_ui -->|"demo requests"| node_api_app
node_nutri_dashboard -->|"uses"| node_client_auth_api
node_household_dashboard -->|"uses"| node_client_auth_api
node_client_auth_api -->|"authenticated API calls"| node_api_app
node_api_app -->|"protects requests"| node_identity
node_api_app -->|"serves"| node_recommendations_api
node_api_app -->|"serves"| node_orders
node_api_app -->|"serves"| node_household_intelligence
node_api_app -->|"serves"| node_pantry_planning
node_identity -->|"stores users and sessions"| node_database
node_swiggy_auth -->|"stores encrypted tokens"| node_database
node_recommendations_api -->|"requests shortlist"| node_agent_pipeline
node_agent_pipeline -->|"derives and ranks candidates"| node_nutrition_ranking
node_agent_pipeline -->|"uses"| node_agent_operations
node_agent_pipeline -->|"retrieves food options"| node_swiggy_mcp
node_orders -->|"uses delegated authorization"| node_swiggy_auth
node_orders -->|"places only after confirmation"| node_swiggy_mcp
node_swiggy_mcp -.->|"uses in demo mode"| node_provider_mock
node_household_intelligence -->|"applies household constraints"| node_pantry_planning
node_pantry_planning -->|"sends stock gaps"| node_grocery_planning
node_household_intelligence -->|"persists household data"| node_database
node_pantry_planning -->|"persists inventory"| node_database
node_grocery_planning -->|"persists lists"| node_database
node_runtime_settings -.->|"selects provider mode"| node_swiggy_mcp
node_runtime_settings -.->|"enforces safety switches"| node_orders
node_deployment -->|"runs Python API"| node_api_app
node_deployment -->|"runs frontend build"| node_product_ui

click node_public_ui "https://github.com/samadarsh/bitewise/blob/main/frontend/app/page.tsx"
click node_product_ui "https://github.com/samadarsh/bitewise/blob/main/frontend/app/app/page.tsx"
click node_demo_ui "https://github.com/samadarsh/bitewise/blob/main/frontend/app/pitch/page.tsx"
click node_nutri_dashboard "https://github.com/samadarsh/bitewise/blob/main/frontend/components/NutriOrderDashboard.tsx"
click node_household_dashboard "https://github.com/samadarsh/bitewise/blob/main/frontend/components/household/HouseholdDashboard.tsx"
click node_client_auth_api "https://github.com/samadarsh/bitewise/blob/main/frontend/lib/auth-context.tsx"
click node_api_app "https://github.com/samadarsh/bitewise/blob/main/backend/main.py"
click node_identity "https://github.com/samadarsh/bitewise/blob/main/backend/auth/user_auth.py"
click node_swiggy_auth "https://github.com/samadarsh/bitewise/blob/main/backend/auth/swiggy_oauth.py"
click node_recommendations_api "https://github.com/samadarsh/bitewise/blob/main/backend/recommendations/service.py"
click node_orders "https://github.com/samadarsh/bitewise/blob/main/backend/orders/state_machine.py"
click node_database "https://github.com/samadarsh/bitewise/blob/main/backend/db/session.py"
click node_agent_pipeline "https://github.com/samadarsh/bitewise/blob/main/agent/pipeline.py"
click node_nutrition_ranking "https://github.com/samadarsh/bitewise/blob/main/agent/ranking.py"
click node_agent_operations "https://github.com/samadarsh/bitewise/blob/main/agent/caching.py"
click node_household_intelligence "https://github.com/samadarsh/bitewise/blob/main/backend/household/intelligence.py"
click node_pantry_planning "https://github.com/samadarsh/bitewise/blob/main/backend/pantry/templates.py"
click node_grocery_planning "https://github.com/samadarsh/bitewise/blob/main/backend/grocery/routes.py"
click node_swiggy_mcp "https://github.com/samadarsh/bitewise/blob/main/backend/mcp/swiggy_client.py"
click node_provider_mock "https://github.com/samadarsh/bitewise/blob/main/mcp/mcp_mock.py"
click node_runtime_settings "https://github.com/samadarsh/bitewise/blob/main/config/settings.py"
click node_deployment "https://github.com/samadarsh/bitewise/blob/main/Dockerfile"

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_public_ui,node_product_ui,node_demo_ui,node_nutri_dashboard,node_household_dashboard,node_client_auth_api toneBlue
class node_api_app,node_identity,node_swiggy_auth,node_recommendations_api,node_orders,node_database toneAmber
class node_agent_pipeline,node_nutrition_ranking,node_agent_operations toneMint
class node_household_intelligence,node_pantry_planning,node_grocery_planning toneRose
class node_swiggy_mcp,node_provider_mock,node_runtime_settings,node_deployment toneIndigo
```

## Components

### Next.js client

- [Public entry](https://github.com/samadarsh/bitewise/blob/main/frontend/app/page.tsx): Next.js route · `frontend/app/page.tsx`
- [Authenticated product UI](https://github.com/samadarsh/bitewise/blob/main/frontend/app/app/page.tsx): Next.js route · `frontend/app/app/page.tsx`
- [Guided demo](https://github.com/samadarsh/bitewise/blob/main/frontend/app/pitch/page.tsx): Next.js route · `frontend/app/pitch/page.tsx`
- [NutriOrder dashboard](https://github.com/samadarsh/bitewise/blob/main/frontend/components/NutriOrderDashboard.tsx): React component · `frontend/components/NutriOrderDashboard.tsx`
- [Household dashboard](https://github.com/samadarsh/bitewise/blob/main/frontend/components/household/HouseholdDashboard.tsx): React component · `frontend/components/household/HouseholdDashboard.tsx`
- [Auth state & API client](https://github.com/samadarsh/bitewise/blob/main/frontend/lib/auth-context.tsx): frontend integration · `frontend/lib/auth-context.tsx`

### FastAPI platform

- [API application](https://github.com/samadarsh/bitewise/blob/main/backend/main.py): FastAPI entry point · Composes all product route domains. · `backend/main.py`
- [User auth & sessions](https://github.com/samadarsh/bitewise/blob/main/backend/auth/user_auth.py): identity boundary · `backend/auth/user_auth.py`
- [Swiggy OAuth PKCE](https://github.com/samadarsh/bitewise/blob/main/backend/auth/swiggy_oauth.py): delegated authorization · Encrypts provider tokens. · `backend/auth/swiggy_oauth.py`
- [Recommendation service](https://github.com/samadarsh/bitewise/blob/main/backend/recommendations/service.py): API service · `backend/recommendations/service.py`
- [Order lifecycle](https://github.com/samadarsh/bitewise/blob/main/backend/orders/state_machine.py): order API · Review and confirmation gate execution. · `backend/orders/state_machine.py`
- [SQLAlchemy persistence](https://github.com/samadarsh/bitewise/blob/main/backend/db/session.py): SQLite/PostgreSQL · `backend/db/session.py`

### NutriOrder intelligence

- [Decision pipeline](https://github.com/samadarsh/bitewise/blob/main/agent/pipeline.py): agent orchestration · Builds explainable meal shortlists. · `agent/pipeline.py`
- [Nutrition & ranking](https://github.com/samadarsh/bitewise/blob/main/agent/ranking.py): decision engine · Targets, estimates, and ranks macro, price, delivery, taste, and confidence tradeoffs. · `agent/ranking.py`
- [Agent operations](https://github.com/samadarsh/bitewise/blob/main/agent/caching.py): cache, memory & resilience · `agent/caching.py`

### SmartPantry

- [Household intelligence](https://github.com/samadarsh/bitewise/blob/main/backend/household/intelligence.py): planning service · Synthesizes membership and dietary constraints. · `backend/household/intelligence.py`
- [Pantry & recipes](https://github.com/samadarsh/bitewise/blob/main/backend/pantry/templates.py): inventory planning · Finds cookable recipes, stock gaps, and low-stock items. · `backend/pantry/templates.py`
- [Grocery list & cart preview](https://github.com/samadarsh/bitewise/blob/main/backend/grocery/routes.py): grocery API · Plans categories and priorities without checkout. · `backend/grocery/routes.py`

### Provider & deployment

- [Swiggy MCP boundary](https://github.com/samadarsh/bitewise/blob/main/backend/mcp/swiggy_client.py): provider client · Provider calls are isolated behind MCP. · `backend/mcp/swiggy_client.py`
- [Mock provider](https://github.com/samadarsh/bitewise/blob/main/mcp/mcp_mock.py): demo provider · Supports local and demo operation. · `mcp/mcp_mock.py`
- [Runtime safety settings](https://github.com/samadarsh/bitewise/blob/main/config/settings.py): configuration boundary · Controls provider mode, credentials, and placement safety switches. · `config/settings.py`
- [Docker deployment](https://github.com/samadarsh/bitewise/blob/main/Dockerfile): container runtime · `Dockerfile`

## Connections

- Public entry → Authenticated product UI: enters
- Authenticated product UI → NutriOrder dashboard: renders
- Authenticated product UI → Household dashboard: renders
- Guided demo → API application: demo requests
- NutriOrder dashboard → Auth state & API client: uses
- Household dashboard → Auth state & API client: uses
- Auth state & API client → API application: authenticated API calls
- API application → User auth & sessions: protects requests
- API application → Recommendation service: serves
- API application → Order lifecycle: serves
- API application → Household intelligence: serves
- API application → Pantry & recipes: serves
- User auth & sessions → SQLAlchemy persistence: stores users and sessions
- Swiggy OAuth PKCE → SQLAlchemy persistence: stores encrypted tokens
- Recommendation service → Decision pipeline: requests shortlist
- Decision pipeline → Nutrition & ranking: derives and ranks candidates
- Decision pipeline → Agent operations: uses
- Decision pipeline → Swiggy MCP boundary: retrieves food options
- Order lifecycle → Swiggy OAuth PKCE: uses delegated authorization
- Order lifecycle → Swiggy MCP boundary: places only after confirmation
- Swiggy MCP boundary → Mock provider: uses in demo mode
- Household intelligence → Pantry & recipes: applies household constraints
- Pantry & recipes → Grocery list & cart preview: sends stock gaps
- Household intelligence → SQLAlchemy persistence: persists household data
- Pantry & recipes → SQLAlchemy persistence: persists inventory
- Grocery list & cart preview → SQLAlchemy persistence: persists lists
- Runtime safety settings → Swiggy MCP boundary: selects provider mode
- Runtime safety settings → Order lifecycle: enforces safety switches
- Docker deployment → API application: runs Python API
- Docker deployment → Authenticated product UI: runs frontend build