# nachiket-mr360/vyapermitra_ai architecture

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

- Interactive diagram: https://gitdiagram.com/nachiket-mr360/vyapermitra_ai
- Repository: https://github.com/nachiket-mr360/vyapermitra_ai

## Overview

VyaparMitra is a voice-first shop assistant with a web dashboard for kirana and grocery owners. The main voice workflow captures speech, transcribes it, parses an intent, then requires confirmation before executing a mutation; the UI also supports product, sales, inventory, analytics, planner, and memory workflows. The graph preserves these documented product areas and the SQLite business-data layer. Relationships are limited to those evidenced by excerpts, the source index, or the README; unsampled route and service wiring is not asserted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/App.tsx) (App navigation), [`frontend/src/hooks/useVoiceSession.ts`](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/hooks/useVoiceSession.ts) (Voice session), [`backend/routes`](https://github.com/nachiket-mr360/vyapermitra_ai/tree/main/backend/routes) (HTTP routes), [`frontend/src/api/client.ts`](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Shop interface"]
  node_app["App navigation<br/>[App.tsx]"]
  node_sales_ui["Sales workspace<br/>[SalesPage.tsx]"]
  node_dashboard["Dashboard<br/>[HomeDashboard.tsx]"]
  node_planner_ui["Planner UI<br/>[Planner.tsx]"]
  node_inventory_ui["Inventory view<br/>[InventoryPage.tsx]"]
  node_insights_ui["Insights view<br/>[InsightsPage.tsx]"]
  node_settings_ui["Settings<br/>[SettingsPage.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_voice["Voice interaction"]
  node_voice_overlay["Voice overlay<br/>[VoiceOverlay.tsx]"]
  node_voice_session["Voice session<br/>[useVoiceSession.ts]"]
  node_audio_capture["Audio capture<br/>[vad.ts]"]
  node_audio_playback["Speech playback<br/>[ttsSession.ts]"]
  node_voice_api["Voice API<br/>[voice.ts]"]
  node_gnani_stt["Prisma STT<br/>[stt.py]"]
end

subgraph group_intent["Intent processing"]
  node_intent_api["Intent API<br/>[intent.ts]"]
  node_intent_parser["Intent parser<br/>[parser.py]"]
  node_intent_executor["Intent executor<br/>[executor.py]"]
  node_llm["Gemini interpreter<br/>[gemini.py]"]
end

subgraph group_business["Shop operations"]
  node_products["Product catalog<br/>[products.py]"]
  node_sales["Sales lifecycle<br/>[sale_lifecycle.py]"]
  node_stock["Stock management<br/>[stock.py]"]
  node_planner["Planner service<br/>[planner.py]"]
  node_analytics["Analytics<br/>[analytics.py]"]
  node_memory["Shop memory<br/>[memory.py]"]
  node_catalog["Catalog matching<br/>[catalog.py]"]
end

subgraph group_platform["Backend platform"]
  node_routes["HTTP routes"]
  node_app_server["Flask application<br/>[app.py]"]
  node_database[("Shop database<br/>[db.py]")]
end

node_owner(("Shop owner"))
node_gnani_service["Gnani service"]

node_owner -->|"uses"| node_app
node_app -->|"shows"| node_dashboard
node_app -->|"shows"| node_sales_ui
node_app -->|"shows"| node_planner_ui
node_app -->|"shows"| node_inventory_ui
node_app -->|"shows"| node_insights_ui
node_app -->|"shows"| node_settings_ui
node_app -->|"opens"| node_voice_overlay
node_voice_overlay -->|"uses"| node_voice_session
node_voice_session -->|"captures"| node_audio_capture
node_voice_session -->|"requests speech"| node_voice_api
node_voice_session -->|"submits transcript"| node_intent_api
node_voice_session -->|"plays speech"| node_audio_playback
node_voice_api -.->|"sends requests"| node_api_client
node_intent_api -.->|"sends requests"| node_api_client
node_intent_api -.->|"calls intent endpoints"| node_routes
node_voice_api -.->|"calls voice endpoints"| node_routes
node_gnani_stt -.->|"requests transcription"| node_gnani_service
node_routes -->|"registered by"| node_app_server
node_routes -.->|"dispatches intent"| node_intent_parser
node_routes -.->|"confirms intent"| node_intent_executor
node_intent_parser -->|"matches products"| node_catalog
node_intent_executor -.->|"executes mutations"| node_sales
node_intent_executor -.->|"executes reminders"| node_planner
node_intent_executor -.->|"executes memory actions"| node_memory
node_products -->|"reads and writes"| node_database
node_sales -->|"reads and writes"| node_database
node_stock -->|"reads and writes"| node_database
node_planner -->|"reads and writes"| node_database
node_products -->|"delegates stock changes"| node_stock
node_sales -->|"applies returns"| node_stock
node_dashboard -->|"fetches data"| node_api_client
node_planner_ui -->|"fetches data"| node_api_client
node_sales_ui -->|"sends requests"| node_api_client
node_llm -.->|"interprets with Gemini"| node_gnani_service

click node_app "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/App.tsx"
click node_sales_ui "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/sales/SalesPage.tsx"
click node_dashboard "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/dashboard/HomeDashboard.tsx"
click node_planner_ui "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/Planner.tsx"
click node_inventory_ui "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/inventory/InventoryPage.tsx"
click node_insights_ui "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/insights/InsightsPage.tsx"
click node_settings_ui "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/settings/SettingsPage.tsx"
click node_api_client "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/client.ts"
click node_voice_overlay "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/voice/VoiceOverlay.tsx"
click node_voice_session "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/hooks/useVoiceSession.ts"
click node_audio_capture "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/audio/vad.ts"
click node_audio_playback "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/audio/ttsSession.ts"
click node_voice_api "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/voice.ts"
click node_intent_api "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/intent.ts"
click node_intent_parser "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/intents/parser.py"
click node_intent_executor "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/intents/executor.py"
click node_llm "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/llm/gemini.py"
click node_routes "https://github.com/nachiket-mr360/vyapermitra_ai/tree/main/backend/routes"
click node_app_server "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/app.py"
click node_products "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/products.py"
click node_sales "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/sale_lifecycle.py"
click node_stock "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/stock.py"
click node_planner "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/planner.py"
click node_analytics "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/analytics.py"
click node_memory "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/memory.py"
click node_database "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/db.py"
click node_catalog "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/catalog.py"
click node_gnani_stt "https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/gnani/stt.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,node_sales_ui,node_dashboard,node_planner_ui,node_inventory_ui,node_insights_ui,node_settings_ui,node_api_client toneBlue
class node_voice_overlay,node_voice_session,node_audio_capture,node_audio_playback,node_voice_api,node_gnani_stt toneAmber
class node_intent_api,node_intent_parser,node_intent_executor,node_llm toneMint
class node_products,node_sales,node_stock,node_planner,node_analytics,node_memory,node_catalog toneRose
class node_routes,node_app_server,node_database,node_owner,node_gnani_service toneIndigo
```

## Components

### Shop interface

- [App navigation](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sales workspace](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/sales/SalesPage.tsx): `frontend/src/components/sales/SalesPage.tsx`
- [Dashboard](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/dashboard/HomeDashboard.tsx): `frontend/src/components/dashboard/HomeDashboard.tsx`
- [Planner UI](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/Planner.tsx): `frontend/src/components/Planner.tsx`
- [Inventory view](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/inventory/InventoryPage.tsx): `frontend/src/components/inventory/InventoryPage.tsx`
- [Insights view](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/insights/InsightsPage.tsx): `frontend/src/components/insights/InsightsPage.tsx`
- [Settings](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/settings/SettingsPage.tsx): `frontend/src/components/settings/SettingsPage.tsx`
- [API client](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Voice interaction

- [Voice overlay](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/components/voice/VoiceOverlay.tsx): `frontend/src/components/voice/VoiceOverlay.tsx`
- [Voice session](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/hooks/useVoiceSession.ts): `frontend/src/hooks/useVoiceSession.ts`
- [Audio capture](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/audio/vad.ts): `frontend/src/audio/vad.ts`
- [Speech playback](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/audio/ttsSession.ts): `frontend/src/audio/ttsSession.ts`
- [Voice API](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/voice.ts): `frontend/src/api/voice.ts`
- [Prisma STT](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/gnani/stt.py): `backend/gnani/stt.py`

### Intent processing

- [Intent API](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/frontend/src/api/intent.ts): `frontend/src/api/intent.ts`
- [Intent parser](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/intents/parser.py): `backend/intents/parser.py`
- [Intent executor](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/intents/executor.py): `backend/intents/executor.py`
- [Gemini interpreter](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/llm/gemini.py): `backend/llm/gemini.py`

### Shop operations

- [Product catalog](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/products.py): `backend/services/products.py`
- [Sales lifecycle](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/sale_lifecycle.py): `backend/services/sale_lifecycle.py`
- [Stock management](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/stock.py): `backend/services/stock.py`
- [Planner service](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/planner.py): `backend/services/planner.py`
- [Analytics](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/analytics.py): `backend/services/analytics.py`
- [Shop memory](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/services/memory.py): `backend/services/memory.py`
- [Catalog matching](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/catalog.py): `backend/catalog.py`

### Backend platform

- [HTTP routes](https://github.com/nachiket-mr360/vyapermitra_ai/tree/main/backend/routes): `backend/routes`
- [Flask application](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/app.py): `backend/app.py`
- [Shop database](https://github.com/nachiket-mr360/vyapermitra_ai/blob/main/backend/db.py): `backend/db.py`

### Other components

- **Shop owner**
- **Gnani service**

## Connections

- Shop owner → App navigation: uses (evidence: `frontend/src/App.tsx`)
- App navigation → Dashboard: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Sales workspace: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Planner UI: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Inventory view: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Insights view: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Settings: shows (evidence: `frontend/src/App.tsx`)
- App navigation → Voice overlay: opens (evidence: `frontend/src/App.tsx`)
- Voice overlay → Voice session: uses (evidence: `frontend/src/components/voice/VoiceOverlay.tsx`)
- Voice session → Audio capture: captures (evidence: `frontend/src/hooks/useVoiceSession.ts`)
- Voice session → Voice API: requests speech (evidence: `frontend/src/hooks/useVoiceSession.ts`)
- Voice session → Intent API: submits transcript (evidence: `frontend/src/hooks/useVoiceSession.ts`)
- Voice session → Speech playback: plays speech (evidence: `frontend/src/hooks/useVoiceSession.ts`)
- Voice API → API client: sends requests
- Intent API → API client: sends requests
- Intent API → HTTP routes: calls intent endpoints
- Voice API → HTTP routes: calls voice endpoints
- Prisma STT → Gnani service: requests transcription
- HTTP routes → Flask application: registered by (evidence: `backend/app.py`)
- HTTP routes → Intent parser: dispatches intent
- HTTP routes → Intent executor: confirms intent (evidence: `backend/routes/sales.py`)
- Intent parser → Catalog matching: matches products (evidence: `backend/intents/ops_parser.py`)
- Intent executor → Sales lifecycle: executes mutations
- Intent executor → Planner service: executes reminders
- Intent executor → Shop memory: executes memory actions
- Product catalog → Shop database: reads and writes (evidence: `backend/services/products.py`)
- Sales lifecycle → Shop database: reads and writes (evidence: `backend/services/sale_lifecycle.py`)
- Stock management → Shop database: reads and writes (evidence: `backend/services/stock.py`)
- Planner service → Shop database: reads and writes (evidence: `backend/services/planner.py`)
- Product catalog → Stock management: delegates stock changes (evidence: `backend/services/products.py`)
- Sales lifecycle → Stock management: applies returns (evidence: `backend/services/sale_lifecycle.py`)
- Dashboard → API client: fetches data (evidence: `frontend/src/components/dashboard/HomeDashboard.tsx`)
- Planner UI → API client: fetches data (evidence: `frontend/src/components/Planner.tsx`)
- Sales workspace → API client: sends requests (evidence: `frontend/src/components/sales/SalesPage.tsx`)
- Gemini interpreter → Gnani service: interprets with Gemini