# shahmeerabdul/khata-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/shahmeerabdul/khata-v2
- Repository: https://github.com/shahmeerabdul/khata-v2

## Overview

Khata is a bilingual, mobile-first ledger for shopkeepers, with voice-driven sales, customer credit, payments, and supplier payables as its main workflow. A shopkeeper records an utterance; the client sends audio to the voice API, whose server pipeline uses Gemini to classify it, resolves customer and purchase records in MongoDB, and returns a result mirrored into the local ledger. The UI also supports manual ledger entry, contacts, entry management, and dashboards. WhatsApp messaging is optional. The voice flow is documented and the API route is sampled; details of the pipeline implementation and most page wiring are represented only where the README or tree supports them.

Main entry points: [`server/src/actions/voice-intent.ts`](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/actions/voice-intent.ts) (Intent pipeline), [`client/lib/store/ledger-store.ts`](https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/store/ledger-store.ts) (Local ledger), [`client/app/record/page.tsx`](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/record/page.tsx) (Record flow), [`client/app/api/customers/delete/route.ts`](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/customers/delete/route.ts) (Customer delete API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Shopkeeper app"]
  node_record["Record flow<br/>[page.tsx]"]
  node_recorder["Audio capture"]
  node_receipt["Confirmation receipt<br/>[page.tsx]"]
  node_ledger_ui["Ledger screens"]
  node_manual_entry["Manual entries"]
  node_contacts_ui["Contacts screens"]
  node_auth["Demo auth<br/>[auth-store.ts]"]
end

subgraph group_voice["Voice processing"]
  node_record_api["Voice record API<br/>[route.ts]"]
  node_commit_api["Voice commit API<br/>[route.ts]"]
  node_undo_api["Voice undo API<br/>[route.ts]"]
  node_pipeline["Intent pipeline<br/>[voice-intent.ts]"]
  node_delete_api["Customer delete API<br/>[route.ts]"]
end

subgraph group_data["Ledger data"]
  node_customers[("Customer records<br/>[customers.ts]")]
  node_purchases[("Purchase records<br/>[purchases.ts]")]
  node_ledger_store[("Local ledger<br/>[ledger-store.ts]")]
end

subgraph group_integrations["External services"]
  node_gemini_client["Intent extraction<br/>[gemini-client.ts]"]
  node_twilio_client["WhatsApp messaging<br/>[twilio-client.ts]"]
end

node_shopkeeper(("Shopkeeper"))
node_gemini["Google Gemini"]
node_mongo[("MongoDB")]
node_local_storage[("Browser storage")]
node_twilio["Twilio WhatsApp"]

node_shopkeeper -->|"records speech"| node_record
node_record -->|"captures audio"| node_recorder
node_record -->|"uploads audio"| node_record_api
node_record_api -->|"runs intent"| node_pipeline
node_commit_api -->|"commits choice"| node_pipeline
node_undo_api -->|"undoes entry"| node_pipeline
node_pipeline -->|"requests intent"| node_gemini_client
node_gemini_client -->|"sends audio"| node_gemini
node_pipeline -->|"resolves customer"| node_customers
node_pipeline -->|"records purchase"| node_purchases
node_customers -->|"reads and writes"| node_mongo
node_purchases -->|"reads and writes"| node_mongo
node_record -->|"mirrors result"| node_ledger_store
node_ledger_store -->|"persists ledger"| node_local_storage
node_ledger_ui -->|"reads ledger"| node_ledger_store
node_manual_entry -->|"updates ledger"| node_ledger_store
node_contacts_ui -->|"reads contacts"| node_ledger_store
node_contacts_ui -->|"requests deletion"| node_delete_api
node_delete_api -->|"deletes customer"| node_customers
node_delete_api -->|"deletes purchases"| node_purchases
node_pipeline -.->|"sends messages"| node_twilio_client
node_twilio_client -.->|"sends WhatsApp"| node_twilio
node_record -->|"shows result"| node_receipt
node_ledger_store -.-> node_auth

click node_record "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/record/page.tsx"
click node_recorder "https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/hooks/useAudioRecorder.ts"
click node_record_api "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/record/route.ts"
click node_commit_api "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/commit/route.ts"
click node_undo_api "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/undo/route.ts"
click node_pipeline "https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/actions/voice-intent.ts"
click node_gemini_client "https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/integrations/gemini-client.ts"
click node_customers "https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/db/customers.ts"
click node_purchases "https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/db/purchases.ts"
click node_ledger_store "https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/store/ledger-store.ts"
click node_receipt "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/record/receipt/page.tsx"
click node_twilio_client "https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/integrations/twilio-client.ts"
click node_ledger_ui "https://github.com/shahmeerabdul/khata-v2/tree/main/client/app"
click node_manual_entry "https://github.com/shahmeerabdul/khata-v2/tree/main/client/app/new"
click node_contacts_ui "https://github.com/shahmeerabdul/khata-v2/tree/main/client/app/contacts"
click node_delete_api "https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/customers/delete/route.ts"
click node_auth "https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/store/auth-store.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_record,node_recorder,node_receipt,node_ledger_ui,node_manual_entry,node_contacts_ui,node_auth toneBlue
class node_record_api,node_commit_api,node_undo_api,node_pipeline,node_delete_api,node_mongo,node_local_storage toneAmber
class node_customers,node_purchases,node_ledger_store toneMint
class node_gemini_client,node_twilio_client toneRose
class node_shopkeeper,node_gemini,node_twilio toneIndigo
```

## Components

### Shopkeeper app

- [Record flow](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/record/page.tsx): `client/app/record/page.tsx`
- [Audio capture](https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/hooks/useAudioRecorder.ts): `client/lib/hooks/useAudioRecorder.ts`
- [Confirmation receipt](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/record/receipt/page.tsx): `client/app/record/receipt/page.tsx`
- [Ledger screens](https://github.com/shahmeerabdul/khata-v2/tree/main/client/app): `client/app`
- [Manual entries](https://github.com/shahmeerabdul/khata-v2/tree/main/client/app/new): `client/app/new`
- [Contacts screens](https://github.com/shahmeerabdul/khata-v2/tree/main/client/app/contacts): `client/app/contacts`
- [Demo auth](https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/store/auth-store.ts): `client/lib/store/auth-store.ts`

### Voice processing

- [Voice record API](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/record/route.ts): `client/app/api/voice/record/route.ts`
- [Voice commit API](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/commit/route.ts): `client/app/api/voice/commit/route.ts`
- [Voice undo API](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/voice/undo/route.ts): `client/app/api/voice/undo/route.ts`
- [Intent pipeline](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/actions/voice-intent.ts): `server/src/actions/voice-intent.ts`
- [Customer delete API](https://github.com/shahmeerabdul/khata-v2/blob/main/client/app/api/customers/delete/route.ts): `client/app/api/customers/delete/route.ts`

### Ledger data

- [Customer records](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/db/customers.ts): `server/src/db/customers.ts`
- [Purchase records](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/db/purchases.ts): `server/src/db/purchases.ts`
- [Local ledger](https://github.com/shahmeerabdul/khata-v2/blob/main/client/lib/store/ledger-store.ts): `client/lib/store/ledger-store.ts`

### External services

- [Intent extraction](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/integrations/gemini-client.ts): `server/src/integrations/gemini-client.ts`
- [WhatsApp messaging](https://github.com/shahmeerabdul/khata-v2/blob/main/server/src/integrations/twilio-client.ts): `server/src/integrations/twilio-client.ts`

### Other components

- **Shopkeeper**
- **Google Gemini**
- **MongoDB**
- **Browser storage**
- **Twilio WhatsApp**

## Connections

- Shopkeeper → Record flow: records speech
- Record flow → Audio capture: captures audio
- Record flow → Voice record API: uploads audio
- Voice record API → Intent pipeline: runs intent
- Voice commit API → Intent pipeline: commits choice
- Voice undo API → Intent pipeline: undoes entry
- Intent pipeline → Intent extraction: requests intent
- Intent extraction → Google Gemini: sends audio
- Intent pipeline → Customer records: resolves customer
- Intent pipeline → Purchase records: records purchase
- Customer records → MongoDB: reads and writes
- Purchase records → MongoDB: reads and writes
- Record flow → Local ledger: mirrors result
- Local ledger → Browser storage: persists ledger
- Ledger screens → Local ledger: reads ledger
- Manual entries → Local ledger: updates ledger
- Contacts screens → Local ledger: reads contacts
- Contacts screens → Customer delete API: requests deletion
- Customer delete API → Customer records: deletes customer
- Customer delete API → Purchase records: deletes purchases
- Intent pipeline → WhatsApp messaging: sends messages
- WhatsApp messaging → Twilio WhatsApp: sends WhatsApp
- Record flow → Confirmation receipt: shows result
- Local ledger → Demo auth