# ahsensahfi78/techmosepos architecture

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

- Interactive diagram: https://gitdiagram.com/ahsensahfi78/techmosepos
- Repository: https://github.com/ahsensahfi78/techmosepos

## Overview

ShoplyPOS is a point-of-sale and retail operations system: staff build and check out sales, while the backend records transactions and updates stock; dashboards and reports expose business status. The Next.js frontend communicates with a FastAPI backend backed by SQLite, with WebSockets distributing stock changes to connected browsers. Beyond checkout, the repository includes inventory, purchasing, ledger/finance, quotations, repairs, warranty, user administration, audit, backup, and eCash capabilities. Several of these modules are unsampled; their presence and routing are visible, but their internal behavior is not inferred here.

Main entry points: [`backend/app/main.py`](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/main.py) (FastAPI entry point), [`frontend/lib/api.ts`](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/lib/api.ts) (API client), [`backend/app/models.py`](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/models.py) (Domain models), [`backend/app/middleware/auth_mw.py`](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/middleware/auth_mw.py) (Authentication middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Storefront"]
  node_pos["Point of sale<br/>[page.tsx]"]
  node_dashboard["Dashboard and reports<br/>[page.tsx]"]
  node_inventory_ui["Inventory screens<br/>[page.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_stock_hook["Live stock hook<br/>[useStock.ts]"]
end

subgraph group_api["API and Access"]
  node_fastapi["FastAPI entry point<br/>[main.py]"]
  node_auth_mw["Authentication middleware<br/>[auth_mw.py]"]
  node_auth["Token and identity logic<br/>[auth.py]"]
  node_permissions["Role permissions<br/>[permissions.py]"]
end

subgraph group_commerce["Sales and Stock"]
  node_sales_routes["Sales and product routes"]
  node_sales_service["Sales processing<br/>[sales_service.py]"]
  node_inventory_routes["Inventory routes<br/>[inventory.py]"]
end

subgraph group_operations["Business Operations"]
  node_purchase_service["Purchasing"]
  node_ledger_service["Party ledger<br/>[ledger_service.py]"]
  node_transactions["Transaction search"]
  node_operations_routes["Business operation routes"]
end

subgraph group_persistence["Data and Sync"]
  node_sqlite[("SQLite database<br/>[database.py]")]
  node_models["Domain models<br/>[models.py]"]
  node_user_repo["User repository<br/>[user_repo.py]"]
  node_audit_repo["Audit repository<br/>[audit_repo.py]"]
  node_ws_manager["WebSocket manager<br/>[manager.py]"]
end

node_staff(("Store staff"))
node_browser_clients(("Connected browsers"))

node_staff -->|"uses"| node_pos
node_pos -.->|"requests sales"| node_frontend_api
node_frontend_api -.->|"calls API"| node_sales_routes
node_dashboard -.->|"requests reports"| node_frontend_api
node_inventory_ui -.->|"requests inventory"| node_frontend_api
node_fastapi -->|"registers routes"| node_sales_routes
node_fastapi -->|"registers routes"| node_operations_routes
node_fastapi -->|"installs middleware"| node_auth_mw
node_auth_mw -->|"decodes tokens"| node_auth
node_auth_mw -->|"loads user"| node_models
node_fastapi -->|"manages connections"| node_ws_manager
node_fastapi -->|"opens sessions"| node_sqlite
node_sales_routes -.->|"delegates sales"| node_sales_service
node_sales_service -->|"updates sale and stock"| node_models
node_purchase_service -->|"uses ledger"| node_ledger_service
node_sales_service -->|"uses ledger"| node_ledger_service
node_transactions -->|"queries records"| node_models
node_user_repo -->|"queries users"| node_models
node_fastapi -->|"bootstraps admin"| node_user_repo
node_fastapi -->|"serves WebSocket"| node_browser_clients
node_fastapi -.->|"broadcasts updates"| node_ws_manager
node_stock_hook -->|"applies stock sync"| node_browser_clients
node_inventory_routes -->|"broadcasts stock"| node_ws_manager
node_operations_routes -.->|"uses ledger"| node_ledger_service
node_operations_routes -.->|"serves transaction feed"| node_transactions

click node_pos "https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/pos/page.tsx"
click node_dashboard "https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/dashboard/page.tsx"
click node_inventory_ui "https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/inventory/page.tsx"
click node_frontend_api "https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/lib/api.ts"
click node_stock_hook "https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/hooks/useStock.ts"
click node_fastapi "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/main.py"
click node_auth_mw "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/middleware/auth_mw.py"
click node_auth "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/auth.py"
click node_permissions "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/permissions.py"
click node_sales_routes "https://github.com/ahsensahfi78/techmosepos/tree/main/backend/app/routers"
click node_sales_service "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/sales_service.py"
click node_inventory_routes "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/routers/inventory.py"
click node_purchase_service "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/purchase_service.py"
click node_ledger_service "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/ledger_service.py"
click node_transactions "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/transaction_service.py"
click node_operations_routes "https://github.com/ahsensahfi78/techmosepos/tree/main/backend/app/routers"
click node_sqlite "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/database.py"
click node_models "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/models.py"
click node_user_repo "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/repositories/user_repo.py"
click node_audit_repo "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/repositories/audit_repo.py"
click node_ws_manager "https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/manager.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_pos,node_dashboard,node_inventory_ui,node_frontend_api,node_stock_hook,node_browser_clients toneBlue
class node_fastapi,node_auth_mw,node_auth,node_permissions toneAmber
class node_sales_routes,node_sales_service,node_inventory_routes toneMint
class node_purchase_service,node_ledger_service,node_transactions,node_operations_routes toneRose
class node_sqlite,node_models,node_user_repo,node_audit_repo,node_ws_manager,node_staff toneIndigo
```

## Components

### Storefront

- [Point of sale](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/pos/page.tsx): `frontend/app/pos/page.tsx`
- [Dashboard and reports](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Inventory screens](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/app/inventory/page.tsx): `frontend/app/inventory/page.tsx`
- [API client](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Live stock hook](https://github.com/ahsensahfi78/techmosepos/blob/main/frontend/hooks/useStock.ts): `frontend/hooks/useStock.ts`

### API and Access

- [FastAPI entry point](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication middleware](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/middleware/auth_mw.py): `backend/app/middleware/auth_mw.py`
- [Token and identity logic](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Role permissions](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/permissions.py): `backend/app/permissions.py`

### Sales and Stock

- [Sales and product routes](https://github.com/ahsensahfi78/techmosepos/tree/main/backend/app/routers): `backend/app/routers`
- [Sales processing](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/sales_service.py): `backend/app/services/sales_service.py`
- [Inventory routes](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/routers/inventory.py): `backend/app/routers/inventory.py`

### Business Operations

- [Purchasing](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/purchase_service.py): `backend/app/services/purchase_service.py`
- [Party ledger](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/ledger_service.py): `backend/app/services/ledger_service.py`
- [Transaction search](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/services/transaction_service.py): `backend/app/services/transaction_service.py`
- [Business operation routes](https://github.com/ahsensahfi78/techmosepos/tree/main/backend/app/routers): `backend/app/routers`

### Data and Sync

- [SQLite database](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain models](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/models.py): `backend/app/models.py`
- [User repository](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/repositories/user_repo.py): `backend/app/repositories/user_repo.py`
- [Audit repository](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/repositories/audit_repo.py): `backend/app/repositories/audit_repo.py`
- [WebSocket manager](https://github.com/ahsensahfi78/techmosepos/blob/main/backend/app/manager.py): `backend/app/manager.py`

### Other components

- **Store staff**
- **Connected browsers**

## Connections

- Store staff → Point of sale: uses (evidence: `README.md`)
- Point of sale → API client: requests sales
- API client → Sales and product routes: calls API
- Dashboard and reports → API client: requests reports
- Inventory screens → API client: requests inventory
- FastAPI entry point → Sales and product routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry point → Business operation routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry point → Authentication middleware: installs middleware (evidence: `backend/app/main.py`)
- Authentication middleware → Token and identity logic: decodes tokens (evidence: `backend/app/middleware/auth_mw.py`)
- Authentication middleware → Domain models: loads user (evidence: `backend/app/middleware/auth_mw.py`)
- FastAPI entry point → WebSocket manager: manages connections (evidence: `backend/app/main.py`)
- FastAPI entry point → SQLite database: opens sessions (evidence: `backend/app/main.py`)
- Sales and product routes → Sales processing: delegates sales
- Sales processing → Domain models: updates sale and stock (evidence: `backend/app/services/sales_service.py`)
- Purchasing → Party ledger: uses ledger (evidence: `backend/app/services/purchase_service.py`)
- Sales processing → Party ledger: uses ledger (evidence: `backend/app/services/sales_service.py`)
- Transaction search → Domain models: queries records (evidence: `backend/app/services/transaction_service.py`)
- User repository → Domain models: queries users (evidence: `backend/app/repositories/user_repo.py`)
- FastAPI entry point → User repository: bootstraps admin (evidence: `backend/app/main.py`)
- FastAPI entry point → Connected browsers: serves WebSocket (evidence: `backend/app/main.py`)
- FastAPI entry point → WebSocket manager: broadcasts updates (evidence: `backend/app/main.py`)
- Live stock hook → Connected browsers: applies stock sync (evidence: `README.md`)
- Inventory routes → WebSocket manager: broadcasts stock (evidence: `backend/app/routers/inventory.py`)
- Business operation routes → Party ledger: uses ledger (evidence: `backend/app/routers/ledger.py`)
- Business operation routes → Transaction search: serves transaction feed
