samadarsh/bitewise

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.