# adithya-charan/shopsahayak architecture

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

- Interactive diagram: https://gitdiagram.com/adithya-charan/shopsahayak
- Repository: https://github.com/adithya-charan/shopsahayak

## Overview

ShopSahayak is a conversational retail business assistant: shopkeepers ask sales or inventory questions by text or voice, and receive answers grounded in business data. Text requests enter FastAPI and pass through NLP, bounded agent orchestration, business tools, analytics or ML, and LLM response generation; voice adds LiveKit and Sarvam speech processing. The repository also includes daily reports, sales and inventory endpoints, forecasting, anomaly detection, restock logic, and optional avatar sessions. The frontend and some voice/provider wiring are documented but not fully shown in the sampled source.

Main entry points: [`app/api/endpoints.py`](https://github.com/adithya-charan/shopsahayak/blob/main/app/api/endpoints.py) (FastAPI routes), [`app/core/agent.py`](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/agent.py) (Query orchestrator), [`app/voice_worker.py`](https://github.com/adithya-charan/shopsahayak/blob/main/app/voice_worker.py) (LiveKit voice worker), [`app/core/tools.py`](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/tools.py) (Business tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_frontend["Web assistant"]
  node_api["FastAPI routes<br/>[endpoints.py]"]
  node_app["Application entry<br/>[main.py]"]
end

subgraph group_assistant["Assistant orchestration"]
  node_agent["Query orchestrator<br/>[agent.py]"]
  node_nlp["Language processing<br/>[nlp.py]"]
  node_sessions[("Conversation history<br/>[session.py]")]
  node_tools["Business tool registry<br/>[tools.py]"]
  node_llm["Response generation<br/>[llm.py]"]
end

subgraph group_business["Retail intelligence"]
  node_analytics["Retail analytics<br/>[engine.py]"]
  node_ml["Forecast and restock<br/>[engine.py]"]
  node_provider["Business data interface<br/>[interfaces.py]"]
  node_synthetic[("Demo business data<br/>[synthetic.py]")]
  node_models["Retail data models<br/>[models.py]"]
end

subgraph group_integrations["Voice and providers"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_sarvam["Sarvam speech<br/>[sarvam.py]"]
  node_voiceworker["LiveKit voice worker<br/>[voice_worker.py]"]
  node_avatar["Avatar sessions<br/>[beyond_presence.py]"]
  node_livekit{{"LiveKit service"}}
  node_groq{{"Groq service"}}
end

node_retailer(("Shopkeeper"))

node_retailer -->|"asks question"| node_frontend
node_frontend -->|"sends requests"| node_api
node_app -->|"registers routes"| node_api
node_api -->|"processes query"| node_agent
node_agent -->|"parses query"| node_nlp
node_agent -->|"reads and stores history"| node_sessions
node_agent -->|"executes selected tools"| node_tools
node_agent -->|"requests tool calls and answer"| node_llm
node_tools -->|"calls analytics"| node_analytics
node_tools -->|"calls ML methods"| node_ml
node_analytics -->|"reads business data"| node_provider
node_ml -->|"reads business data"| node_provider
node_synthetic -->|"implements interface"| node_provider
node_synthetic -->|"creates retail records"| node_models
node_api -->|"serves stock queries"| node_analytics
node_api -->|"provides ML services"| node_ml
node_api -->|"initializes data provider"| node_synthetic
node_llm -->|"generates completions"| node_groq
node_voiceworker -->|"joins room"| node_livekit
node_voiceworker -->|"processes transcript"| node_agent
node_voiceworker -.->|"transcribes and speaks"| node_sarvam
node_retailer -.->|"streams voice"| node_livekit
node_api -->|"creates avatar session"| node_avatar
node_avatar -.->|"uses room"| node_livekit
node_config -->|"configures provider"| node_llm
node_config -->|"configures provider"| node_avatar

click node_frontend "https://github.com/adithya-charan/shopsahayak/tree/main/ShopSahayak-AI-Retail-Assistant"
click node_api "https://github.com/adithya-charan/shopsahayak/blob/main/app/api/endpoints.py"
click node_app "https://github.com/adithya-charan/shopsahayak/blob/main/app/main.py"
click node_agent "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/agent.py"
click node_nlp "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/nlp.py"
click node_sessions "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/session.py"
click node_tools "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/tools.py"
click node_llm "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/llm.py"
click node_analytics "https://github.com/adithya-charan/shopsahayak/blob/main/app/analytics/engine.py"
click node_ml "https://github.com/adithya-charan/shopsahayak/blob/main/app/ml/engine.py"
click node_provider "https://github.com/adithya-charan/shopsahayak/blob/main/app/data/interfaces.py"
click node_synthetic "https://github.com/adithya-charan/shopsahayak/blob/main/app/data/synthetic.py"
click node_models "https://github.com/adithya-charan/shopsahayak/blob/main/app/data/models.py"
click node_config "https://github.com/adithya-charan/shopsahayak/blob/main/app/config.py"
click node_sarvam "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/sarvam.py"
click node_voiceworker "https://github.com/adithya-charan/shopsahayak/blob/main/app/voice_worker.py"
click node_avatar "https://github.com/adithya-charan/shopsahayak/blob/main/app/core/beyond_presence.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_frontend,node_api,node_app toneBlue
class node_agent,node_nlp,node_sessions,node_tools,node_llm toneAmber
class node_analytics,node_ml,node_provider,node_synthetic,node_models toneMint
class node_config,node_sarvam,node_voiceworker,node_avatar,node_livekit,node_groq toneRose
class node_retailer toneIndigo
```

## Components

### User interaction

- [Web assistant](https://github.com/adithya-charan/shopsahayak/tree/main/ShopSahayak-AI-Retail-Assistant): `ShopSahayak-AI-Retail-Assistant`
- [FastAPI routes](https://github.com/adithya-charan/shopsahayak/blob/main/app/api/endpoints.py): `app/api/endpoints.py`
- [Application entry](https://github.com/adithya-charan/shopsahayak/blob/main/app/main.py): `app/main.py`

### Assistant orchestration

- [Query orchestrator](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/agent.py): `app/core/agent.py`
- [Language processing](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/nlp.py): `app/core/nlp.py`
- [Conversation history](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/session.py): `app/core/session.py`
- [Business tool registry](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/tools.py): `app/core/tools.py`
- [Response generation](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/llm.py): `app/core/llm.py`

### Retail intelligence

- [Retail analytics](https://github.com/adithya-charan/shopsahayak/blob/main/app/analytics/engine.py): `app/analytics/engine.py`
- [Forecast and restock](https://github.com/adithya-charan/shopsahayak/blob/main/app/ml/engine.py): `app/ml/engine.py`
- [Business data interface](https://github.com/adithya-charan/shopsahayak/blob/main/app/data/interfaces.py): `app/data/interfaces.py`
- [Demo business data](https://github.com/adithya-charan/shopsahayak/blob/main/app/data/synthetic.py): `app/data/synthetic.py`
- [Retail data models](https://github.com/adithya-charan/shopsahayak/blob/main/app/data/models.py): `app/data/models.py`

### Voice and providers

- [Runtime configuration](https://github.com/adithya-charan/shopsahayak/blob/main/app/config.py): `app/config.py`
- [Sarvam speech](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/sarvam.py): `app/core/sarvam.py`
- [LiveKit voice worker](https://github.com/adithya-charan/shopsahayak/blob/main/app/voice_worker.py): `app/voice_worker.py`
- [Avatar sessions](https://github.com/adithya-charan/shopsahayak/blob/main/app/core/beyond_presence.py): `app/core/beyond_presence.py`
- **LiveKit service**
- **Groq service**

### Other components

- **Shopkeeper**

## Connections

- Shopkeeper → Web assistant: asks question (evidence: `README.md`)
- Web assistant → FastAPI routes: sends requests (evidence: `README.md`)
- Application entry → FastAPI routes: registers routes (evidence: `app/main.py`)
- FastAPI routes → Query orchestrator: processes query (evidence: `app/api/endpoints.py`)
- Query orchestrator → Language processing: parses query (evidence: `app/core/agent.py`)
- Query orchestrator → Conversation history: reads and stores history (evidence: `app/core/agent.py`)
- Query orchestrator → Business tool registry: executes selected tools (evidence: `app/core/agent.py`)
- Query orchestrator → Response generation: requests tool calls and answer (evidence: `app/core/agent.py`)
- Business tool registry → Retail analytics: calls analytics (evidence: `app/core/tools.py`)
- Business tool registry → Forecast and restock: calls ML methods (evidence: `app/core/tools.py`)
- Retail analytics → Business data interface: reads business data (evidence: `app/analytics/engine.py`)
- Forecast and restock → Business data interface: reads business data (evidence: `app/ml/engine.py`)
- Demo business data → Business data interface: implements interface (evidence: `app/data/synthetic.py`)
- Demo business data → Retail data models: creates retail records (evidence: `app/data/synthetic.py`)
- FastAPI routes → Retail analytics: serves stock queries (evidence: `app/api/endpoints.py`)
- FastAPI routes → Forecast and restock: provides ML services (evidence: `app/api/endpoints.py`)
- FastAPI routes → Demo business data: initializes data provider (evidence: `app/api/endpoints.py`)
- Response generation → Groq service: generates completions (evidence: `README.md`)
- LiveKit voice worker → LiveKit service: joins room (evidence: `app/voice_worker.py`)
- LiveKit voice worker → Query orchestrator: processes transcript (evidence: `app/voice_worker.py`)
- LiveKit voice worker → Sarvam speech: transcribes and speaks (evidence: `README.md`)
- Shopkeeper → LiveKit service: streams voice (evidence: `README.md`)
- FastAPI routes → Avatar sessions: creates avatar session (evidence: `app/api/endpoints.py`)
- Avatar sessions → LiveKit service: uses room (evidence: `README.md`)
- Runtime configuration → Response generation: configures provider (evidence: `app/core/llm.py`)
- Runtime configuration → Avatar sessions: configures provider (evidence: `app/core/beyond_presence.py`)
