# murali4421/retailpulse architecture

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

- Interactive diagram: https://gitdiagram.com/murali4421/retailpulse
- Repository: https://github.com/murali4421/retailpulse

## Overview

RetailPulse is a shop-management SPA and backend for cashier checkout, stock operations, reporting, multi-store administration, identity, and compliance. The main flow is staff using the web app, which routes to operational views; those views use an API client to reach backend routes and domain controllers, which persist state and emit audit events. Offline sales use local storage and a sync manager to reconcile with the API. README capabilities such as backup, reports, MFA, and compliance are retained; unsampled implementation details are represented by their exact directories.

Main entry points: [`frontend/src/App.tsx`](https://github.com/murali4421/retailpulse/blob/main/frontend/src/App.tsx) (Retail SPA), [`backend/src/routes/api.js`](https://github.com/murali4421/retailpulse/blob/main/backend/src/routes/api.js) (API routes), [`frontend/src/services/api.ts`](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/api.ts) (API and WebSocket client), [`backend/src/data/store.js`](https://github.com/murali4421/retailpulse/blob/main/backend/src/data/store.js) (Shop database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Retail Operations"]
  node_spa["Retail SPA<br/>[App.tsx]"]
  node_pos["Checkout POS<br/>[POS.tsx]"]
  node_inventory_ui["Inventory UI<br/>[Inventory.tsx]"]
  node_dashboard["Trends dashboard<br/>[Dashboard.tsx]"]
  node_sales_history["Sales history<br/>[SalesHistory.tsx]"]
  node_scanner["Barcode scanner"]
  node_daily_report["Daily reports"]
  node_security_ui["Security audit UI<br/>[SecurityAudit.tsx]"]
  node_compliance_ui["Compliance hub<br/>[Compliance.tsx]"]
  node_store_admin["Store administration<br/>[MultiStore.tsx]"]
  node_settings_ui["Settings UI<br/>[Settings.tsx]"]
end

subgraph group_offline["Offline and Sync"]
  node_offline_db[("Offline sales database<br/>[offlineDb.ts]")]
  node_crypto["Local encryption<br/>[cryptoStorage.ts]"]
  node_sync["Sync manager<br/>[syncManager.ts]"]
end

subgraph group_gateway["API and Identity"]
  node_api_client["API and WebSocket client<br/>[api.ts]"]
  node_auth_context["Session and permissions<br/>[authContext.tsx]"]
  node_routes["API routes<br/>[api.js]"]
  node_auth_controller["Authentication<br/>[authController.js]"]
  node_oidc["OIDC tokens<br/>[oidcService.js]"]
  node_mfa["MFA service<br/>[mfaService.js]"]
end

subgraph group_domain["Shop Services"]
  node_inventory["Inventory operations"]
  node_sales["Sales processing<br/>[salesController.js]"]
  node_compliance["Privacy operations"]
  node_stores["Store operations<br/>[storeController.js]"]
  node_backup["Backup snapshots<br/>[backupService.js]"]
  node_audit_controller["Audit queries<br/>[auditController.js]"]
  node_backup_controller["Backup controls"]
  node_settings_controller["Shop settings"]
end

subgraph group_state["Persistence and Audit"]
  node_database[("Shop database<br/>[store.js]")]
  node_audit[("Audit and threat rules<br/>[auditService.js]")]
end

node_staff(("Shop staff"))

node_staff -->|"uses"| node_spa
node_spa -->|"routes to"| node_pos
node_spa -->|"routes to"| node_inventory_ui
node_spa -->|"routes to"| node_dashboard
node_spa -->|"routes to"| node_sales_history
node_spa -->|"routes to"| node_security_ui
node_spa -->|"routes to"| node_compliance_ui
node_spa -->|"routes to"| node_store_admin
node_spa -->|"routes to"| node_settings_ui
node_pos -->|"opens"| node_scanner
node_inventory_ui -->|"opens"| node_scanner
node_dashboard -->|"opens"| node_daily_report
node_sales_history -->|"opens"| node_daily_report
node_pos -->|"queues sales"| node_offline_db
node_offline_db -->|"encrypts data"| node_crypto
node_sync -->|"reads queue"| node_offline_db
node_sync -->|"submits sales"| node_api_client
node_pos -->|"requests operations"| node_api_client
node_inventory_ui -->|"requests operations"| node_api_client
node_dashboard -->|"requests data"| node_api_client
node_sales_history -->|"requests data"| node_api_client
node_security_ui -->|"requests logs"| node_api_client
node_compliance_ui -->|"requests safeguards"| node_api_client
node_api_client -->|"calls REST API"| node_routes
node_routes -->|"dispatches auth"| node_auth_controller
node_routes -->|"dispatches inventory"| node_inventory
node_routes -->|"dispatches sales"| node_sales
node_routes -->|"dispatches audit"| node_audit_controller
node_routes -->|"dispatches compliance"| node_compliance
node_routes -->|"dispatches backups"| node_backup_controller
node_routes -->|"dispatches stores"| node_stores
node_routes -->|"dispatches settings"| node_settings_controller
node_auth_context -->|"authenticates through"| node_api_client
node_auth_controller -->|"issues tokens"| node_oidc
node_auth_controller -->|"verifies factors"| node_mfa
node_auth_controller -->|"reads and saves"| node_database
node_inventory -->|"reads and saves"| node_database
node_sales -->|"reads and saves"| node_database
node_inventory -->|"records events"| node_audit
node_sales -->|"records events"| node_audit
node_auth_controller -->|"records events"| node_audit
node_audit_controller -->|"queries logs"| node_audit
node_compliance -->|"reads data"| node_database
node_compliance -->|"records events"| node_audit
node_stores -->|"reads and saves"| node_database
node_backup_controller -.->|"triggers snapshots"| node_backup
node_backup -->|"reads records"| node_database
node_backup -->|"records activity"| node_audit

click node_spa "https://github.com/murali4421/retailpulse/blob/main/frontend/src/App.tsx"
click node_pos "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/POS.tsx"
click node_inventory_ui "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Inventory.tsx"
click node_dashboard "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Dashboard.tsx"
click node_sales_history "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/SalesHistory.tsx"
click node_scanner "https://github.com/murali4421/retailpulse/blob/main/frontend/src/components/BarcodeScannerModal.tsx"
click node_daily_report "https://github.com/murali4421/retailpulse/blob/main/frontend/src/components/DailyReportModal.tsx"
click node_security_ui "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/SecurityAudit.tsx"
click node_compliance_ui "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Compliance.tsx"
click node_store_admin "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/MultiStore.tsx"
click node_settings_ui "https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Settings.tsx"
click node_api_client "https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/api.ts"
click node_auth_context "https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/authContext.tsx"
click node_routes "https://github.com/murali4421/retailpulse/blob/main/backend/src/routes/api.js"
click node_auth_controller "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/authController.js"
click node_oidc "https://github.com/murali4421/retailpulse/blob/main/backend/src/services/oidcService.js"
click node_mfa "https://github.com/murali4421/retailpulse/blob/main/backend/src/services/mfaService.js"
click node_inventory "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/inventoryController.js"
click node_sales "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/salesController.js"
click node_compliance "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/complianceController.js"
click node_stores "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/storeController.js"
click node_backup "https://github.com/murali4421/retailpulse/blob/main/backend/src/services/backupService.js"
click node_offline_db "https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/offlineDb.ts"
click node_crypto "https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/cryptoStorage.ts"
click node_sync "https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/syncManager.ts"
click node_database "https://github.com/murali4421/retailpulse/blob/main/backend/src/data/store.js"
click node_audit "https://github.com/murali4421/retailpulse/blob/main/backend/src/services/auditService.js"
click node_audit_controller "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/auditController.js"
click node_backup_controller "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/backupController.js"
click node_settings_controller "https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/settingsController.js"

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_spa,node_pos,node_inventory_ui,node_dashboard,node_sales_history,node_scanner,node_daily_report,node_security_ui,node_compliance_ui,node_store_admin,node_settings_ui toneBlue
class node_offline_db,node_crypto,node_sync toneAmber
class node_api_client,node_auth_context,node_routes,node_auth_controller,node_oidc,node_mfa toneMint
class node_inventory,node_sales,node_compliance,node_stores,node_backup,node_audit_controller,node_backup_controller,node_settings_controller toneRose
class node_database,node_audit,node_staff toneIndigo
```

## Components

### Retail Operations

- [Retail SPA](https://github.com/murali4421/retailpulse/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Checkout POS](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/POS.tsx): `frontend/src/pages/POS.tsx`
- [Inventory UI](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Inventory.tsx): `frontend/src/pages/Inventory.tsx`
- [Trends dashboard](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Sales history](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/SalesHistory.tsx): `frontend/src/pages/SalesHistory.tsx`
- [Barcode scanner](https://github.com/murali4421/retailpulse/blob/main/frontend/src/components/BarcodeScannerModal.tsx): `frontend/src/components/BarcodeScannerModal.tsx`
- [Daily reports](https://github.com/murali4421/retailpulse/blob/main/frontend/src/components/DailyReportModal.tsx): `frontend/src/components/DailyReportModal.tsx`
- [Security audit UI](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/SecurityAudit.tsx): `frontend/src/pages/SecurityAudit.tsx`
- [Compliance hub](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Compliance.tsx): `frontend/src/pages/Compliance.tsx`
- [Store administration](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/MultiStore.tsx): `frontend/src/pages/MultiStore.tsx`
- [Settings UI](https://github.com/murali4421/retailpulse/blob/main/frontend/src/pages/Settings.tsx): `frontend/src/pages/Settings.tsx`

### Offline and Sync

- [Offline sales database](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/offlineDb.ts): `frontend/src/services/offlineDb.ts`
- [Local encryption](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/cryptoStorage.ts): `frontend/src/services/cryptoStorage.ts`
- [Sync manager](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/syncManager.ts): `frontend/src/services/syncManager.ts`

### API and Identity

- [API and WebSocket client](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Session and permissions](https://github.com/murali4421/retailpulse/blob/main/frontend/src/services/authContext.tsx): `frontend/src/services/authContext.tsx`
- [API routes](https://github.com/murali4421/retailpulse/blob/main/backend/src/routes/api.js): `backend/src/routes/api.js`
- [Authentication](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [OIDC tokens](https://github.com/murali4421/retailpulse/blob/main/backend/src/services/oidcService.js): `backend/src/services/oidcService.js`
- [MFA service](https://github.com/murali4421/retailpulse/blob/main/backend/src/services/mfaService.js): `backend/src/services/mfaService.js`

### Shop Services

- [Inventory operations](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/inventoryController.js): `backend/src/controllers/inventoryController.js`
- [Sales processing](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/salesController.js): `backend/src/controllers/salesController.js`
- [Privacy operations](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/complianceController.js): `backend/src/controllers/complianceController.js`
- [Store operations](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/storeController.js): `backend/src/controllers/storeController.js`
- [Backup snapshots](https://github.com/murali4421/retailpulse/blob/main/backend/src/services/backupService.js): `backend/src/services/backupService.js`
- [Audit queries](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/auditController.js): `backend/src/controllers/auditController.js`
- [Backup controls](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/backupController.js): `backend/src/controllers/backupController.js`
- [Shop settings](https://github.com/murali4421/retailpulse/blob/main/backend/src/controllers/settingsController.js): `backend/src/controllers/settingsController.js`

### Persistence and Audit

- [Shop database](https://github.com/murali4421/retailpulse/blob/main/backend/src/data/store.js): `backend/src/data/store.js`
- [Audit and threat rules](https://github.com/murali4421/retailpulse/blob/main/backend/src/services/auditService.js): `backend/src/services/auditService.js`

### Other components

- **Shop staff**

## Connections

- Shop staff → Retail SPA: uses (evidence: `README.md`)
- Retail SPA → Checkout POS: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Inventory UI: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Trends dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Sales history: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Security audit UI: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Compliance hub: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Store administration: routes to (evidence: `frontend/src/App.tsx`)
- Retail SPA → Settings UI: routes to (evidence: `frontend/src/App.tsx`)
- Checkout POS → Barcode scanner: opens (evidence: `frontend/src/pages/POS.tsx`)
- Inventory UI → Barcode scanner: opens (evidence: `frontend/src/pages/Inventory.tsx`)
- Trends dashboard → Daily reports: opens (evidence: `frontend/src/pages/Dashboard.tsx`)
- Sales history → Daily reports: opens (evidence: `frontend/src/pages/SalesHistory.tsx`)
- Checkout POS → Offline sales database: queues sales (evidence: `frontend/src/pages/POS.tsx`)
- Offline sales database → Local encryption: encrypts data (evidence: `frontend/src/services/offlineDb.ts`)
- Sync manager → Offline sales database: reads queue (evidence: `frontend/src/services/syncManager.ts`)
- Sync manager → API and WebSocket client: submits sales (evidence: `frontend/src/services/syncManager.ts`)
- Checkout POS → API and WebSocket client: requests operations (evidence: `README.md`)
- Inventory UI → API and WebSocket client: requests operations (evidence: `frontend/src/pages/Inventory.tsx`)
- Trends dashboard → API and WebSocket client: requests data (evidence: `frontend/src/pages/Dashboard.tsx`)
- Sales history → API and WebSocket client: requests data (evidence: `frontend/src/pages/SalesHistory.tsx`)
- Security audit UI → API and WebSocket client: requests logs (evidence: `frontend/src/pages/SecurityAudit.tsx`)
- Compliance hub → API and WebSocket client: requests safeguards (evidence: `frontend/src/pages/Compliance.tsx`)
- API and WebSocket client → API routes: calls REST API (evidence: `README.md`)
- API routes → Authentication: dispatches auth (evidence: `backend/src/routes/api.js`)
- API routes → Inventory operations: dispatches inventory (evidence: `backend/src/routes/api.js`)
- API routes → Sales processing: dispatches sales (evidence: `backend/src/routes/api.js`)
- API routes → Audit queries: dispatches audit (evidence: `backend/src/routes/api.js`)
- API routes → Privacy operations: dispatches compliance (evidence: `backend/src/routes/api.js`)
- API routes → Backup controls: dispatches backups (evidence: `backend/src/routes/api.js`)
- API routes → Store operations: dispatches stores (evidence: `backend/src/routes/api.js`)
- API routes → Shop settings: dispatches settings (evidence: `backend/src/routes/api.js`)
- Session and permissions → API and WebSocket client: authenticates through (evidence: `frontend/src/services/authContext.tsx`)
- Authentication → OIDC tokens: issues tokens (evidence: `backend/src/controllers/authController.js`)
- Authentication → MFA service: verifies factors (evidence: `backend/src/controllers/authController.js`)
- Authentication → Shop database: reads and saves (evidence: `backend/src/controllers/authController.js`)
- Inventory operations → Shop database: reads and saves (evidence: `backend/src/controllers/inventoryController.js`)
- Sales processing → Shop database: reads and saves (evidence: `backend/src/controllers/salesController.js`)
- Inventory operations → Audit and threat rules: records events (evidence: `backend/src/controllers/inventoryController.js`)
- Sales processing → Audit and threat rules: records events (evidence: `backend/src/controllers/salesController.js`)
- Authentication → Audit and threat rules: records events (evidence: `backend/src/controllers/authController.js`)
- Audit queries → Audit and threat rules: queries logs (evidence: `backend/src/controllers/auditController.js`)
- Privacy operations → Shop database: reads data (evidence: `backend/src/controllers/complianceController.js`)
- Privacy operations → Audit and threat rules: records events (evidence: `backend/src/controllers/complianceController.js`)
- Store operations → Shop database: reads and saves (evidence: `backend/src/controllers/storeController.js`)
- Backup controls → Backup snapshots: triggers snapshots
- Backup snapshots → Shop database: reads records (evidence: `backend/src/services/backupService.js`)
- Backup snapshots → Audit and threat rules: records activity (evidence: `backend/src/services/backupService.js`)