Dashboard/Technical Architecture & System Docs

DABBAIQ SPECIFICATION • STITCH HANDOFF • PHASE 6

System Architecture & Technical Specification

Comprehensive, source-grounded technical documentation of the DabbaIQ Master Kitchen Operations Desk: architecture, data pipelines, local Gemma AI integration, database schemas, and reproduction workflows.

1. Problem Statement & User Workflows

The Commercial Dabba Challenge

In Mumbai and metropolitan commercial kitchens, thousands of lunch dabbas are prepped under stringent 3-hour windows (09:00 — 12:00 IST). Kitchen managers traditionally face unpredictable corporate attendance, sudden monsoon transit delays, and volatile APMC mandi ingredient rates.

Over-preparation leads to 12–18% direct food scrap loss, while under-preparation causes missed delivery slots across South Mumbai and BKC corporate delivery circuits.

Target Users & Daily Workflow

Head Chefs & Ops Directors: Establish morning batch targets, review safety buffers, and verify ingredient stock before cooking begins.
Kitchen Line Leads: Log dispatches, mark low-stock alerts, and reconcile unsold tiffins into the waste log at 14:30 IST.
Procurement Managers: Benchmark commodity grain prices against Vashi APMC mandi indices via SerpAPI.

2. System Architecture & Data Flow

Presentation Layer

Next.js 16 (Turbopack)

React 19, Vanilla Tailwind, Epilogue & Manrope

• Dual-Deck Command Bar• 12 Screen Routes

Core Application Engine

Python FastAPI

Uvicorn ASGI • AsyncIO • Pydantic v2

• Strict /api Contracts• 101 Automated Tests

Persistence & AI

MongoDB Atlas + Gemma 2

Motor Async • Ollama Local Inference

• TimescaleDB Hypertables• SerpAPI Mandi

End-to-End Operational Flow:

1. Ingest DemandAdvance standing orders + Weather + Past 7-day sales

2. Gemma ReasoningOn-premise LLM calculates batch target & buffer

3. BOM & Mandi SyncSerpAPI benchmarks wholesale APMC commodity rates

4. Lock & ReconcileKitchen dispatch confirmed; unsold logged to scrap loss

3. Operational Module Status Matrix

Module	Route	Status	API Contract	Description
Master Kitchen Desk	/	OPERATIONAL	GET /api/dashboard	Real-time shift summary, portions target, critical stock alarms, and 7-day sales velocity chart.
3D Tiffin Experience	/experience	OPERATIONAL	Static / Client State Machine	Interactive scroll-driven 4-tier SS304 tiffin disassembly with live CAD elevation HUD (Z+85mm).
AI Preparation Planner	/planner	OPERATIONAL	GET /api/plans, POST /api/plans	Portion demand forecasting with Gemma 2 AI reasoning, safety buffer slider, and BOM shortage detection.
Inventory & Stock Ledger	/inventory	OPERATIONAL	GET /api/inventory, POST /api/inventory/adjust	Raw commodity stock management, threshold warnings, reorder alerts, and SerpAPI APMC mandi benchmarking.
Recipe Library & Costing	/recipes	OPERATIONAL	GET /api/recipes, POST /api/recipes	Heritage Bombay tiffin BOM formulas, dynamic per-dabba costing based on ingredient prices, and multilingual menu generation.
Sales & Dispatch Ledger	/sales	OPERATIONAL	GET /api/sales, POST /api/sales	Fast meal dispatch logging, date/period filters, revenue tracking, and CSV transaction batch imports.
Waste Tracker & Scrap Loss	/waste	OPERATIONAL	GET /api/waste, POST /api/waste	Food scrap auditing with sunken ingredient cost estimation and loss prevention intelligence.
Business & Operations Reports	/reports	OPERATIONAL	GET /api/reports/summary, GET /api/reports/export	P&L rollups, ingredient consumption charts, waste cost ratios, and automated CSV data streams.
Station Diagnostics & Hardware	/settings	OPERATIONAL	GET /api/health, GET /api/integrations/status	MUM-04 station hardware calibration, latency heartbeats, database ping tests, and model diagnostics.

4. Verified Technology Stack

Next.js 16 + React 19

Turbopack enabled. Static and dynamic routing with client-side reactive ledger state.

FastAPI (Python 3.13)

High-concurrency ASGI server with native Pydantic v2 schemas and OpenAPI generation.

MongoDB Atlas

Async Motor driver storing ingredient catalogs, BOM recipes, sales ledgers, and prep plans.

Ollama + Gemma 2

On-premise local inference (`gemma2:latest`). Zero external data egress; zero cloud AI token leakage.

SerpAPI Wholesale

Live Google Shopping commodity price indexing for Vashi APMC wholesale grain rates.

Tiger Data / Timescale

Time-series hypertables tracking commodity price volatility and historical inflation trends.

5. Backend API Contracts & Endpoints

Method	Endpoint Route	Operational Function	Schema / Contract
GET	/api/health	Comprehensive database & partner telemetry check	HealthResponse
GET	/api/dashboard	Shift overview, expected volume, KPI counters, sales chart data	DashboardResponse
POST	/api/plans/generate	Runs predictive forecast and Gemma AI reasoning	PlanCreateRequest
GET	/api/inventory	Fetches raw ingredient catalog & reorder levels	IngredientListResponse
POST	/api/inventory/adjust	Adjusts stock levels with reason logging	InventoryAdjustment
GET	/api/recipes	Master recipe library with BOM ingredient ratios	RecipeListResponse
GET	/api/sales	Sales transaction ledger with date/meal filters	SalesListResponse
POST	/api/sales	Logs quick sale or corporate circuit order	SaleCreate
GET	/api/waste	Food loss & scrap audit logs with sunk costs	WasteListResponse
GET	/api/reports/summary	Financial P&L rollups across selected dates	ReportSummaryResponse

6. Known Limitations & Graceful Fallback Modes

Ollama AI Offline Fallback

When Ollama is offline or Gemma 2 is not pulled locally, the preparation planner automatically falls back to deterministic 7-day weighted moving averages. Kitchen planning never blocks on LLM availability.

Database Unconfigured / Demo Mode

If MongoDB Atlas URI is unconfigured or unreachable, the system runs safely with seeded in-memory demo fixtures clearly badged as `is_demo: true` to prevent data corruption.

SerpAPI Mandi Rate Limiting

When SerpAPI free monthly quota is exhausted (HTTP 429), the wholesale price engine gracefully uses the latest cached mandi benchmark or unit cost stored in the ingredient record.

3D Storyboard GPU Fallback

On mobile or low-power devices where WebGL or hardware acceleration is constrained, the `/experience` page serves pixel-crisp studio stage renders and elevation HUD indicators with zero scroll jank.

7. Privacy, Security & DPDP Notice

DabbaIQ is designed for kitchen privacy under the Digital Personal Data Protection (DPDP) Act, 2023.

Zero Cloud AI Egress: Gemma 2 inference runs completely on-premise inside the kitchen local network via Ollama. No recipe formulas, client dietary requests, or portion records are sent to cloud LLM providers.
Credential Isolation: No database passwords, SerpAPI keys, or session tokens are ever rendered in the browser UI, client JavaScript bundles, or HTTP response headers.
Audit Logging: Inventory adjustments and scrap waste logs maintain immutable audit timestamps without customer PII.

8. Local Run & Reproduction Instructions

1. Start FastAPI Backend:

cd dabbaiq/backend && python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

2. Run Backend Pytest Suite:

cd dabbaiq/backend && python -m pytest tests -v

3. Start Next.js Development Server:

cd dabbaiq/frontend && npm run dev

4. Run Production Build Validation:

cd dabbaiq/frontend && npm run build