# sasikiranambati/shop-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/sasikiranambati/shop-pulse
- Repository: https://github.com/sasikiranambati/shop-pulse

## Overview

Shelfora is an offline-first grocery-management and invoice-intelligence platform for Kirana retailers. The principal workflow is store staff recording sales or scanning supplier invoices, then managing inventory and reviewing business insights; billing can also be voice-driven. The React client communicates with a FastAPI backend, while local caching and queued mutations support offline operation and later synchronization. Invoice OCR is a distinct extraction and audit-workbook workflow. The graph combines README-documented capabilities with sampled calls; several routes and frontend feature implementations were not sampled, so their internal links are intentionally limited.

Main entry points: [`src/App.tsx`](https://github.com/sasikiranambati/shop-pulse/blob/main/src/App.tsx) (Shelfora App), [`src/api/client.ts`](https://github.com/sasikiranambati/shop-pulse/blob/main/src/api/client.ts) (HTTP Client), [`backend/services/grocery_ocr/pipeline/invoice_pipeline.py`](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/pipeline/invoice_pipeline.py) (Invoice Pipeline), [`src/pages/Sales.tsx`](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Sales.tsx) (POS Billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Store Client"]
  node_web["Shelfora App<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
end

subgraph group_commerce["Retail Operations"]
  node_sales["POS Billing<br/>[Sales.tsx]"]
  node_voice["Voice Billing<br/>[VoiceBillModal.tsx]"]
  node_inventory["Inventory<br/>[Inventory.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_insights["Demand Insights<br/>[Insights.tsx]"]
end

subgraph group_intelligence["Invoice Intelligence"]
  node_invoicescan["Invoice Scanner<br/>[InvoiceScanner.tsx]"]
  node_ocr_pipeline["Invoice Pipeline"]
  node_ocr_engine["OCR Engine<br/>[ocr_engine.py]"]
  node_ai_interpret["AI Interpretation<br/>[service.py]"]
  node_workbooks["Audit Workbooks<br/>[storage_manager.py]"]
end

subgraph group_backend["API and Data"]
  node_api_client["HTTP Client<br/>[client.ts]"]
  node_api_routes["REST Routes"]
  node_api_router["Route Registry<br/>[main.py]"]
  node_db[("Retail Database<br/>[session.py]")]
end

subgraph group_resilience["Offline and Devices"]
  node_offline["Offline Queue and Sync<br/>[syncService.ts]"]
  node_device["Scale and Counter<br/>[scaleService.ts]"]
end

node_staff(("Store Staff"))
node_external_ai{{"AI Providers"}}

node_staff -->|"uses"| node_web
node_web -->|"provides session"| node_auth
node_web -->|"routes to"| node_sales
node_web -->|"routes to"| node_inventory
node_web -->|"routes to"| node_dashboard
node_web -->|"routes to"| node_insights
node_web -->|"routes to"| node_invoicescan
node_sales -.->|"records sales"| node_api_client
node_sales -.->|"queues mutations"| node_offline
node_voice -.->|"submits voice bill"| node_api_client
node_inventory -.->|"updates stock"| node_api_client
node_dashboard -.->|"requests metrics"| node_api_client
node_insights -.->|"requests forecasts"| node_api_client
node_invoicescan -.->|"uploads invoice"| node_api_client
node_api_client -.->|"calls"| node_api_routes
node_api_router -->|"registers"| node_api_routes
node_api_routes -.->|"dispatches invoice"| node_ocr_pipeline
node_ocr_pipeline -->|"recognizes pages"| node_ocr_engine
node_ocr_pipeline -->|"interprets items"| node_ai_interpret
node_ocr_pipeline -->|"stores workbook"| node_workbooks
node_ocr_pipeline -->|"avoids database writes"| node_db
node_ai_interpret -.->|"uses provider"| node_external_ai
node_offline -.->|"syncs mutations"| node_api_client
node_staff -.->|"weighs goods"| node_device

click node_web "https://github.com/sasikiranambati/shop-pulse/blob/main/src/App.tsx"
click node_auth "https://github.com/sasikiranambati/shop-pulse/blob/main/src/context/AuthContext.tsx"
click node_sales "https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Sales.tsx"
click node_voice "https://github.com/sasikiranambati/shop-pulse/blob/main/src/components/VoiceBillModal.tsx"
click node_inventory "https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Inventory.tsx"
click node_dashboard "https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Dashboard.tsx"
click node_insights "https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Insights.tsx"
click node_invoicescan "https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/InvoiceScanner.tsx"
click node_api_client "https://github.com/sasikiranambati/shop-pulse/blob/main/src/api/client.ts"
click node_api_routes "https://github.com/sasikiranambati/shop-pulse/tree/main/backend/api/routes"
click node_api_router "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/api/main.py"
click node_ocr_pipeline "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/pipeline/invoice_pipeline.py"
click node_ocr_engine "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/engines/ocr_engine.py"
click node_ai_interpret "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/ai/service.py"
click node_workbooks "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/excel/storage_manager.py"
click node_db "https://github.com/sasikiranambati/shop-pulse/blob/main/backend/db/session.py"
click node_offline "https://github.com/sasikiranambati/shop-pulse/blob/main/src/services/syncService.ts"
click node_device "https://github.com/sasikiranambati/shop-pulse/blob/main/src/services/scaleService.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_web,node_auth toneBlue
class node_sales,node_voice,node_inventory,node_dashboard,node_insights toneAmber
class node_invoicescan,node_ocr_pipeline,node_ocr_engine,node_ai_interpret,node_workbooks toneMint
class node_api_client,node_api_routes,node_api_router,node_db toneRose
class node_offline,node_device,node_staff,node_external_ai toneIndigo
```

## Components

### Store Client

- [Shelfora App](https://github.com/sasikiranambati/shop-pulse/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/sasikiranambati/shop-pulse/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`

### Retail Operations

- [POS Billing](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Sales.tsx): `src/pages/Sales.tsx`
- [Voice Billing](https://github.com/sasikiranambati/shop-pulse/blob/main/src/components/VoiceBillModal.tsx): `src/components/VoiceBillModal.tsx`
- [Inventory](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Inventory.tsx): `src/pages/Inventory.tsx`
- [Dashboard](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Demand Insights](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/Insights.tsx): `src/pages/Insights.tsx`

### Invoice Intelligence

- [Invoice Scanner](https://github.com/sasikiranambati/shop-pulse/blob/main/src/pages/InvoiceScanner.tsx): `src/pages/InvoiceScanner.tsx`
- [Invoice Pipeline](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/pipeline/invoice_pipeline.py): `backend/services/grocery_ocr/pipeline/invoice_pipeline.py`
- [OCR Engine](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/engines/ocr_engine.py): `backend/services/grocery_ocr/engines/ocr_engine.py`
- [AI Interpretation](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/ai/service.py): `backend/services/grocery_ocr/ai/service.py`
- [Audit Workbooks](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/services/grocery_ocr/excel/storage_manager.py): `backend/services/grocery_ocr/excel/storage_manager.py`

### API and Data

- [HTTP Client](https://github.com/sasikiranambati/shop-pulse/blob/main/src/api/client.ts): `src/api/client.ts`
- [REST Routes](https://github.com/sasikiranambati/shop-pulse/tree/main/backend/api/routes): `backend/api/routes`
- [Route Registry](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/api/main.py): `backend/api/main.py`
- [Retail Database](https://github.com/sasikiranambati/shop-pulse/blob/main/backend/db/session.py): `backend/db/session.py`

### Offline and Devices

- [Offline Queue and Sync](https://github.com/sasikiranambati/shop-pulse/blob/main/src/services/syncService.ts): `src/services/syncService.ts`
- [Scale and Counter](https://github.com/sasikiranambati/shop-pulse/blob/main/src/services/scaleService.ts): `src/services/scaleService.ts`

### Other components

- **Store Staff**
- **AI Providers**

## Connections

- Store Staff → Shelfora App: uses (evidence: `README.md`)
- Shelfora App → Authentication: provides session (evidence: `src/App.tsx`)
- Shelfora App → POS Billing: routes to (evidence: `src/App.tsx`)
- Shelfora App → Inventory: routes to (evidence: `src/App.tsx`)
- Shelfora App → Dashboard: routes to (evidence: `src/App.tsx`)
- Shelfora App → Demand Insights: routes to (evidence: `src/App.tsx`)
- Shelfora App → Invoice Scanner: routes to (evidence: `src/App.tsx`)
- POS Billing → HTTP Client: records sales
- POS Billing → Offline Queue and Sync: queues mutations
- Voice Billing → HTTP Client: submits voice bill
- Inventory → HTTP Client: updates stock
- Dashboard → HTTP Client: requests metrics
- Demand Insights → HTTP Client: requests forecasts
- Invoice Scanner → HTTP Client: uploads invoice (evidence: `README.md`)
- HTTP Client → REST Routes: calls (evidence: `README.md`)
- Route Registry → REST Routes: registers (evidence: `backend/api/main.py`)
- REST Routes → Invoice Pipeline: dispatches invoice (evidence: `README.md`)
- Invoice Pipeline → OCR Engine: recognizes pages (evidence: `backend/services/grocery_ocr/pipeline/invoice_pipeline.py`)
- Invoice Pipeline → AI Interpretation: interprets items (evidence: `backend/services/grocery_ocr/pipeline/invoice_pipeline.py`)
- Invoice Pipeline → Audit Workbooks: stores workbook (evidence: `backend/services/grocery_ocr/pipeline/invoice_pipeline.py`)
- Invoice Pipeline → Retail Database: avoids database writes (evidence: `backend/services/grocery_ocr/pipeline/invoice_pipeline.py`)
- AI Interpretation → AI Providers: uses provider (evidence: `backend/services/grocery_ocr/ai/service.py`)
- Offline Queue and Sync → HTTP Client: syncs mutations (evidence: `README.md`)
- Store Staff → Scale and Counter: weighs goods (evidence: `README.md`)
