# goprocker/sathyabamaexpress architecture

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

- Interactive diagram: https://gitdiagram.com/goprocker/sathyabamaexpress
- Repository: https://github.com/goprocker/sathyabamaexpress

## Overview

The code describes a household-intelligence application, branded LIVORA in API comments, with a web experience, API, deterministic household-domain logic, agent workflows and integrations. The README contains only the title “Sathyabama Express,” so it does not document product capabilities; the feature routes and API excerpts provide the main capability evidence. The principal workflow is a user entering through the web router, whose pages can use query hooks and the API; the API routes work to domain and agent services backed by shared state. Some feature-to-API wiring is not shown, so those links are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/api/src/app.ts) (HTTP API), [`packages/agents/src/index.ts`](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/agents/src/index.ts) (Agent workflows), [`packages/domain/src/meal-engine.ts`](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/meal-engine.ts) (Meal engine), [`packages/life/src/service.ts`](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/service.ts) (Life service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application<br/>[main.tsx]"]
  node_router["Page router<br/>[router.tsx]"]
  node_household_pages["Household pages"]
  node_mobility_page["Mobility<br/>[MobilityPage.tsx]"]
  node_life_pages["Life features"]
  node_query_hooks["Query hooks<br/>[queries.ts]"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_api["API surface"]
  node_api_app["HTTP API<br/>[app.ts]"]
  node_life_routes["Life routes<br/>[life-routes.ts]"]
end

subgraph group_domain["Household logic"]
  node_store[("Application state<br/>[index.ts]")]
  node_inventory["Inventory engine"]
  node_meal["Meal engine<br/>[meal-engine.ts]"]
  node_ripple["Ripple engine<br/>[ripple-engine.ts]"]
  node_units["Unit normalization<br/>[unit-normalizer.ts]"]
  node_forecast["Forecast engine<br/>[forecast-engine.ts]"]
  node_life_service["Life service<br/>[service.ts]"]
  node_life_engine["Life intelligence<br/>[engine.ts]"]
  node_life_data["Life data<br/>[data.ts]"]
end

subgraph group_agents["Agent workflows"]
  node_agent_workflows["Agent workflows<br/>[index.ts]"]
  node_voice_agent["Voice agent<br/>[voice-agent.ts]"]
end

subgraph group_integrations["External integrations"]
  node_openai["OpenAI adapter<br/>[openai-adapter.ts]"]
  node_sarvam["Sarvam adapter<br/>[sarvam-adapter.ts]"]
  node_snapserve["Snapserve adapter"]
end

node_user(("Household user"))
node_vendors(("Retail vendors"))

node_user -->|"uses"| node_webapp
node_webapp -->|"renders routes"| node_router
node_router -->|"routes to"| node_household_pages
node_router -->|"routes to"| node_mobility_page
node_household_pages -.->|"loads data"| node_query_hooks
node_query_hooks -->|"calls"| node_web_api
node_user -->|"requests"| node_api_app
node_api_app -->|"registers routes"| node_life_routes
node_life_routes -->|"calls"| node_life_service
node_api_app -->|"uses"| node_store
node_api_app -->|"runs workflows"| node_agent_workflows
node_api_app -->|"uses"| node_inventory
node_api_app -->|"uses"| node_meal
node_api_app -->|"uses"| node_forecast
node_api_app -->|"uses"| node_ripple
node_api_app -->|"checks integration"| node_snapserve
node_life_service -->|"uses"| node_life_engine
node_life_service -->|"loads"| node_life_data
node_life_engine -->|"uses"| node_life_data
node_inventory -->|"updates state"| node_store
node_meal -->|"updates state"| node_store
node_meal -->|"formats quantities"| node_units
node_inventory -->|"normalizes units"| node_units
node_ripple -->|"simulates meals"| node_meal
node_ripple -->|"formats quantities"| node_units
node_agent_workflows -->|"records workflow"| node_store
node_agent_workflows -->|"parses with"| node_openai
node_agent_workflows -->|"transcribes with"| node_sarvam
node_agent_workflows -->|"resolves vendor"| node_snapserve
node_agent_workflows -->|"simulates meals"| node_meal
node_voice_agent -->|"calls workflows"| node_agent_workflows
node_voice_agent -->|"parses intent"| node_openai
node_agent_workflows -.->|"proposes calls"| node_vendors
node_life_pages -.->|"uses life package"| node_life_service

click node_webapp "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/main.tsx"
click node_router "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/router.tsx"
click node_household_pages "https://github.com/goprocker/sathyabamaexpress/tree/main/apps/web/src/features"
click node_mobility_page "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/features/mobility/MobilityPage.tsx"
click node_life_pages "https://github.com/goprocker/sathyabamaexpress/tree/main/apps/web/src/features"
click node_query_hooks "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/hooks/queries.ts"
click node_web_api "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/lib/api.ts"
click node_api_app "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/api/src/app.ts"
click node_life_routes "https://github.com/goprocker/sathyabamaexpress/blob/main/apps/api/src/life-routes.ts"
click node_store "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/db/src/index.ts"
click node_inventory "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/inventory-engine.ts"
click node_meal "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/meal-engine.ts"
click node_ripple "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/ripple-engine.ts"
click node_units "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/unit-normalizer.ts"
click node_forecast "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/forecast-engine.ts"
click node_life_service "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/service.ts"
click node_life_engine "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/engine.ts"
click node_life_data "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/data.ts"
click node_agent_workflows "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/agents/src/index.ts"
click node_voice_agent "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/agents/src/voice-agent.ts"
click node_openai "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/openai-adapter.ts"
click node_sarvam "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/sarvam-adapter.ts"
click node_snapserve "https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/snapserve-adapter.ts"

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_webapp,node_router,node_household_pages,node_mobility_page,node_life_pages,node_query_hooks,node_web_api,node_user toneBlue
class node_api_app,node_life_routes toneAmber
class node_store,node_inventory,node_meal,node_ripple,node_units,node_forecast,node_life_service,node_life_engine,node_life_data toneMint
class node_agent_workflows,node_voice_agent toneRose
class node_openai,node_sarvam,node_snapserve,node_vendors toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Page router](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/router.tsx): `apps/web/src/router.tsx`
- [Household pages](https://github.com/goprocker/sathyabamaexpress/tree/main/apps/web/src/features): `apps/web/src/features`
- [Mobility](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/features/mobility/MobilityPage.tsx): `apps/web/src/features/mobility/MobilityPage.tsx`
- [Life features](https://github.com/goprocker/sathyabamaexpress/tree/main/apps/web/src/features): `apps/web/src/features`
- [Query hooks](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/hooks/queries.ts): `apps/web/src/hooks/queries.ts`
- [Web API client](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API surface

- [HTTP API](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Life routes](https://github.com/goprocker/sathyabamaexpress/blob/main/apps/api/src/life-routes.ts): `apps/api/src/life-routes.ts`

### Household logic

- [Application state](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`
- [Inventory engine](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/inventory-engine.ts): `packages/domain/src/inventory-engine.ts`
- [Meal engine](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/meal-engine.ts): `packages/domain/src/meal-engine.ts`
- [Ripple engine](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/ripple-engine.ts): `packages/domain/src/ripple-engine.ts`
- [Unit normalization](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/unit-normalizer.ts): `packages/domain/src/unit-normalizer.ts`
- [Forecast engine](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/domain/src/forecast-engine.ts): `packages/domain/src/forecast-engine.ts`
- [Life service](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/service.ts): `packages/life/src/service.ts`
- [Life intelligence](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/engine.ts): `packages/life/src/engine.ts`
- [Life data](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/life/src/data.ts): `packages/life/src/data.ts`

### Agent workflows

- [Agent workflows](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/agents/src/index.ts): `packages/agents/src/index.ts`
- [Voice agent](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/agents/src/voice-agent.ts): `packages/agents/src/voice-agent.ts`

### External integrations

- [OpenAI adapter](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/openai-adapter.ts): `packages/integrations/src/openai-adapter.ts`
- [Sarvam adapter](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/sarvam-adapter.ts): `packages/integrations/src/sarvam-adapter.ts`
- [Snapserve adapter](https://github.com/goprocker/sathyabamaexpress/blob/main/packages/integrations/src/snapserve-adapter.ts): `packages/integrations/src/snapserve-adapter.ts`

### Other components

- **Household user**
- **Retail vendors**

## Connections

- Household user → Web application: uses
- Web application → Page router: renders routes (evidence: `apps/web/src/main.tsx`)
- Page router → Household pages: routes to (evidence: `apps/web/src/router.tsx`)
- Page router → Mobility: routes to (evidence: `apps/web/src/router.tsx`)
- Household pages → Query hooks: loads data
- Query hooks → Web API client: calls (evidence: `apps/web/src/hooks/queries.ts`)
- Household user → HTTP API: requests
- HTTP API → Life routes: registers routes (evidence: `apps/api/src/app.ts`)
- Life routes → Life service: calls (evidence: `apps/api/src/life-routes.ts`)
- HTTP API → Application state: uses (evidence: `apps/api/src/app.ts`)
- HTTP API → Agent workflows: runs workflows (evidence: `apps/api/src/app.ts`)
- HTTP API → Inventory engine: uses (evidence: `apps/api/src/app.ts`)
- HTTP API → Meal engine: uses (evidence: `apps/api/src/app.ts`)
- HTTP API → Forecast engine: uses (evidence: `apps/api/src/app.ts`)
- HTTP API → Ripple engine: uses (evidence: `apps/api/src/app.ts`)
- HTTP API → Snapserve adapter: checks integration (evidence: `apps/api/src/app.ts`)
- Life service → Life intelligence: uses (evidence: `packages/life/src/service.ts`)
- Life service → Life data: loads (evidence: `packages/life/src/service.ts`)
- Life intelligence → Life data: uses (evidence: `packages/life/src/engine.ts`)
- Inventory engine → Application state: updates state (evidence: `packages/domain/src/inventory-engine.ts`)
- Meal engine → Application state: updates state (evidence: `packages/domain/src/meal-engine.ts`)
- Meal engine → Unit normalization: formats quantities (evidence: `packages/domain/src/meal-engine.ts`)
- Inventory engine → Unit normalization: normalizes units (evidence: `packages/domain/src/inventory-engine.ts`)
- Ripple engine → Meal engine: simulates meals (evidence: `packages/domain/src/ripple-engine.ts`)
- Ripple engine → Unit normalization: formats quantities (evidence: `packages/domain/src/ripple-engine.ts`)
- Agent workflows → Application state: records workflow (evidence: `packages/agents/src/index.ts`)
- Agent workflows → OpenAI adapter: parses with (evidence: `packages/agents/src/index.ts`)
- Agent workflows → Sarvam adapter: transcribes with (evidence: `packages/agents/src/index.ts`)
- Agent workflows → Snapserve adapter: resolves vendor (evidence: `packages/agents/src/index.ts`)
- Agent workflows → Meal engine: simulates meals (evidence: `packages/agents/src/index.ts`)
- Voice agent → Agent workflows: calls workflows (evidence: `packages/agents/src/voice-agent.ts`)
- Voice agent → OpenAI adapter: parses intent (evidence: `packages/agents/src/voice-agent.ts`)
- Agent workflows → Retail vendors: proposes calls
- Life features → Life service: uses life package