# 24skater/stewardpos architecture

> Architecture diagram of the GitHub repository 24skater/stewardpos, 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/24skater/stewardpos
- Repository: https://github.com/24skater/stewardpos

## Overview

StewardPOS is a self-hosted point-of-sale system for small shops. A cashier uses the register UI to submit item intent; the backend recalculates prices and totals, obtains payment approval, and persists an approved order before returning a receipt. The map also preserves inventory, returns, till/register management, services and quotes, reporting, and administration. Connections follow the README’s documented architecture and money flow or visible frontend wiring; unsampled route and service internals are represented by their existing directories, without guessing their call graph.

Main entry points: [`backend/src/api/routes`](https://github.com/24skater/stewardpos/tree/main/backend/src/api/routes) (Commerce API routes), [`backend/src/api/routes/orders.ts`](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/orders.ts) (Order processing), [`backend/src/app.ts`](https://github.com/24skater/stewardpos/blob/main/backend/src/app.ts) (Express application), [`backend/src/storage/index.ts`](https://github.com/24skater/stewardpos/blob/main/backend/src/storage/index.ts) (Storage selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Register UI"]
  node_registerui["Register screens<br/>[POS.tsx]"]
  node_servicepos["Services POS<br/>[ServicesPos.tsx]"]
  node_app["Web app routing<br/>[App.tsx]"]
  node_sdk["Typed API SDK<br/>[index.ts]"]
  node_apiclient["API client<br/>[api-client.ts]"]
  node_authui["Session and permissions<br/>[auth.ts]"]
end

subgraph group_api["API and access"]
  node_server["Express application<br/>[app.ts]"]
  node_routes["Commerce API routes"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
end

subgraph group_domain["Commerce operations"]
  node_orders["Order processing<br/>[orders.ts]"]
  node_pricing["Server pricing<br/>[pricing.ts]"]
  node_catalog["Catalog and inventory<br/>[products.ts]"]
  node_terminalgateway["Terminal gateway<br/>[terminalGateway.ts]"]
  node_returns["Returns and refunds<br/>[returns.ts]"]
  node_registers["Registers and shifts<br/>[registers.ts]"]
  node_services["Services and quotes<br/>[services.ts]"]
end

subgraph group_infra["Adapters and state"]
  node_terminaladapters["Payment terminals"]
  node_database["Database service<br/>[database.ts]"]
  node_postgres[("Postgres adapter<br/>[PostgresAdapter.ts]")]
  node_sqlite[("SQLite adapter<br/>[SQLiteAdapter.ts]")]
  node_storage["Storage selection<br/>[index.ts]"]
  node_storageport["Storage port<br/>[StoragePort.ts]"]
  node_localstorage["Local storage"]
  node_s3storage["S3 storage"]
end

subgraph group_admin["Management"]
  node_adminui["Admin screens"]
  node_reports["Reports and exports<br/>[reports.ts]"]
end

node_cashier(("Cashier"))
node_externalterminal(("Payment terminal"))

node_cashier -->|"enters sale"| node_registerui
node_app -->|"routes to"| node_registerui
node_app -->|"routes to"| node_servicepos
node_app -->|"routes to"| node_adminui
node_registerui -.->|"requests data"| node_sdk
node_servicepos -->|"calls"| node_sdk
node_adminui -->|"calls"| node_sdk
node_sdk -->|"uses"| node_apiclient
node_authui -->|"requests session"| node_apiclient
node_apiclient -->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_routes
node_server -->|"mounts route"| node_authroutes
node_routes -.->|"includes"| node_orders
node_orders -->|"re-prices"| node_pricing
node_orders -->|"reads prices"| node_catalog
node_orders -->|"requests charge"| node_terminalgateway
node_terminalgateway -.->|"dispatches"| node_terminaladapters
node_terminaladapters -->|"charges"| node_externalterminal
node_orders -->|"writes approved order"| node_database
node_database -->|"selects adapter"| node_postgres
node_database -->|"selects adapter"| node_sqlite
node_routes -.->|"includes"| node_returns
node_routes -.->|"includes"| node_registers
node_routes -.->|"includes"| node_services
node_adminui -.->|"views reports"| node_reports
node_server -->|"serves uploads"| node_storage
node_storage -->|"implements"| node_storageport
node_storage -->|"selects adapter"| node_localstorage
node_storage -->|"selects adapter"| node_s3storage

click node_registerui "https://github.com/24skater/stewardpos/blob/main/src/pages/POS.tsx"
click node_servicepos "https://github.com/24skater/stewardpos/blob/main/src/pages/ServicesPos.tsx"
click node_adminui "https://github.com/24skater/stewardpos/tree/main/src/pages/admin"
click node_app "https://github.com/24skater/stewardpos/blob/main/src/App.tsx"
click node_sdk "https://github.com/24skater/stewardpos/blob/main/src/lib/api/index.ts"
click node_apiclient "https://github.com/24skater/stewardpos/blob/main/src/lib/api-client.ts"
click node_authui "https://github.com/24skater/stewardpos/blob/main/src/lib/auth.ts"
click node_server "https://github.com/24skater/stewardpos/blob/main/backend/src/app.ts"
click node_routes "https://github.com/24skater/stewardpos/tree/main/backend/src/api/routes"
click node_authroutes "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/auth.ts"
click node_orders "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/orders.ts"
click node_pricing "https://github.com/24skater/stewardpos/blob/main/backend/src/services/pricing.ts"
click node_catalog "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/products.ts"
click node_terminalgateway "https://github.com/24skater/stewardpos/blob/main/backend/src/services/terminalGateway.ts"
click node_terminaladapters "https://github.com/24skater/stewardpos/blob/main/backend/src/terminal/TerminalAdapterFactory.ts"
click node_database "https://github.com/24skater/stewardpos/blob/main/backend/src/services/database.ts"
click node_postgres "https://github.com/24skater/stewardpos/blob/main/backend/src/adapters/db/PostgresAdapter.ts"
click node_sqlite "https://github.com/24skater/stewardpos/blob/main/backend/src/adapters/db/SQLiteAdapter.ts"
click node_returns "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/returns.ts"
click node_registers "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/registers.ts"
click node_services "https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/services.ts"
click node_reports "https://github.com/24skater/stewardpos/blob/main/backend/src/services/reports.ts"
click node_storage "https://github.com/24skater/stewardpos/blob/main/backend/src/storage/index.ts"
click node_storageport "https://github.com/24skater/stewardpos/blob/main/backend/src/storage/StoragePort.ts"
click node_localstorage "https://github.com/24skater/stewardpos/blob/main/backend/src/storage/LocalStorageAdapter.ts"
click node_s3storage "https://github.com/24skater/stewardpos/blob/main/backend/src/storage/S3StorageAdapter.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_registerui,node_servicepos,node_app,node_sdk,node_apiclient,node_authui toneBlue
class node_server,node_routes,node_authroutes toneAmber
class node_orders,node_pricing,node_catalog,node_terminalgateway,node_returns,node_registers,node_services toneMint
class node_terminaladapters,node_database,node_postgres,node_sqlite,node_storage,node_storageport,node_localstorage,node_s3storage toneRose
class node_adminui,node_reports,node_cashier,node_externalterminal toneIndigo
```

## Components

### Register UI

- [Register screens](https://github.com/24skater/stewardpos/blob/main/src/pages/POS.tsx): `src/pages/POS.tsx`
- [Services POS](https://github.com/24skater/stewardpos/blob/main/src/pages/ServicesPos.tsx): `src/pages/ServicesPos.tsx`
- [Web app routing](https://github.com/24skater/stewardpos/blob/main/src/App.tsx): `src/App.tsx`
- [Typed API SDK](https://github.com/24skater/stewardpos/blob/main/src/lib/api/index.ts): `src/lib/api/index.ts`
- [API client](https://github.com/24skater/stewardpos/blob/main/src/lib/api-client.ts): `src/lib/api-client.ts`
- [Session and permissions](https://github.com/24skater/stewardpos/blob/main/src/lib/auth.ts): `src/lib/auth.ts`

### API and access

- [Express application](https://github.com/24skater/stewardpos/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Commerce API routes](https://github.com/24skater/stewardpos/tree/main/backend/src/api/routes): `backend/src/api/routes`
- [Authentication routes](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/auth.ts): `backend/src/api/routes/auth.ts`

### Commerce operations

- [Order processing](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/orders.ts): `backend/src/api/routes/orders.ts`
- [Server pricing](https://github.com/24skater/stewardpos/blob/main/backend/src/services/pricing.ts): `backend/src/services/pricing.ts`
- [Catalog and inventory](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/products.ts): `backend/src/api/routes/products.ts`
- [Terminal gateway](https://github.com/24skater/stewardpos/blob/main/backend/src/services/terminalGateway.ts): `backend/src/services/terminalGateway.ts`
- [Returns and refunds](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/returns.ts): `backend/src/api/routes/returns.ts`
- [Registers and shifts](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/registers.ts): `backend/src/api/routes/registers.ts`
- [Services and quotes](https://github.com/24skater/stewardpos/blob/main/backend/src/api/routes/services.ts): `backend/src/api/routes/services.ts`

### Adapters and state

- [Payment terminals](https://github.com/24skater/stewardpos/blob/main/backend/src/terminal/TerminalAdapterFactory.ts): `backend/src/terminal/TerminalAdapterFactory.ts`
- [Database service](https://github.com/24skater/stewardpos/blob/main/backend/src/services/database.ts): `backend/src/services/database.ts`
- [Postgres adapter](https://github.com/24skater/stewardpos/blob/main/backend/src/adapters/db/PostgresAdapter.ts): `backend/src/adapters/db/PostgresAdapter.ts`
- [SQLite adapter](https://github.com/24skater/stewardpos/blob/main/backend/src/adapters/db/SQLiteAdapter.ts): `backend/src/adapters/db/SQLiteAdapter.ts`
- [Storage selection](https://github.com/24skater/stewardpos/blob/main/backend/src/storage/index.ts): `backend/src/storage/index.ts`
- [Storage port](https://github.com/24skater/stewardpos/blob/main/backend/src/storage/StoragePort.ts): `backend/src/storage/StoragePort.ts`
- [Local storage](https://github.com/24skater/stewardpos/blob/main/backend/src/storage/LocalStorageAdapter.ts): `backend/src/storage/LocalStorageAdapter.ts`
- [S3 storage](https://github.com/24skater/stewardpos/blob/main/backend/src/storage/S3StorageAdapter.ts): `backend/src/storage/S3StorageAdapter.ts`

### Management

- [Admin screens](https://github.com/24skater/stewardpos/tree/main/src/pages/admin): `src/pages/admin`
- [Reports and exports](https://github.com/24skater/stewardpos/blob/main/backend/src/services/reports.ts): `backend/src/services/reports.ts`

### Other components

- **Cashier**
- **Payment terminal**

## Connections

- Cashier → Register screens: enters sale (evidence: `README.md`)
- Web app routing → Register screens: routes to (evidence: `src/App.tsx`)
- Web app routing → Services POS: routes to (evidence: `src/App.tsx`)
- Web app routing → Admin screens: routes to (evidence: `src/App.tsx`)
- Register screens → Typed API SDK: requests data
- Services POS → Typed API SDK: calls (evidence: `src/pages/ServicesPos.tsx`)
- Admin screens → Typed API SDK: calls (evidence: `src/pages/admin/AdminServices.tsx`)
- Typed API SDK → API client: uses (evidence: `src/lib/api/index.ts`)
- Session and permissions → API client: requests session (evidence: `src/lib/auth.ts`)
- API client → Express application: HTTP requests (evidence: `README.md`)
- Express application → Commerce API routes: mounts routes (evidence: `backend/src/app.ts`)
- Express application → Authentication routes: mounts route (evidence: `backend/src/app.ts`)
- Commerce API routes → Order processing: includes
- Order processing → Server pricing: re-prices (evidence: `README.md`)
- Order processing → Catalog and inventory: reads prices (evidence: `README.md`)
- Order processing → Terminal gateway: requests charge (evidence: `README.md`)
- Terminal gateway → Payment terminals: dispatches
- Payment terminals → Payment terminal: charges (evidence: `README.md`)
- Order processing → Database service: writes approved order (evidence: `README.md`)
- Database service → Postgres adapter: selects adapter (evidence: `backend/src/services/database.ts`)
- Database service → SQLite adapter: selects adapter (evidence: `backend/src/services/database.ts`)
- Commerce API routes → Returns and refunds: includes
- Commerce API routes → Registers and shifts: includes
- Commerce API routes → Services and quotes: includes
- Admin screens → Reports and exports: views reports
- Express application → Storage selection: serves uploads (evidence: `backend/src/app.ts`)
- Storage selection → Storage port: implements (evidence: `backend/src/storage/index.ts`)
- Storage selection → Local storage: selects adapter (evidence: `backend/src/storage/index.ts`)
- Storage selection → S3 storage: selects adapter (evidence: `backend/src/storage/index.ts`)