# nuimanlp/srisurart-pos-flutter architecture

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

- Interactive diagram: https://gitdiagram.com/nuimanlp/srisurart-pos-flutter
- Repository: https://github.com/nuimanlp/srisurart-pos-flutter

## Overview

Srisurart Autopart POS is a Thai-first, offline-capable point-of-sale client backed by a multi-tenant NestJS API. The principal workflow is counter staff ringing up a sale, with stock and payment-related business rules enforced transactionally; supporting workflows cover catalogue and purchasing, returns and quotes, customer/mechanic accounts, shifts, reporting, and owner review. The README documents the Flutter-to-API architecture and backend services. Flutter implementation files and most backend domain implementations were not sampled, so their internal calls are not inferred here.

Main entry points: [`server/src`](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src) (NestJS API), [`server/src/sales/sales.controller.ts`](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sales.controller.ts) (Sales checkout), [`server/src/idempotency/idempotency.service.ts`](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/idempotency/idempotency.service.ts) (Idempotent writes), [`server/src/common/guards/tenant.guard.ts`](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/common/guards/tenant.guard.ts) (Tenant authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["POS client"]
  node_flutter["Flutter POS"]
end

subgraph group_access["API access"]
  node_api["NestJS API"]
  node_tenant_auth["Tenant authentication<br/>[tenant.guard.ts]"]
end

subgraph group_commerce["Sales and stock"]
  node_sales["Sales checkout"]
  node_sale_rules["Sale processing<br/>[sales.service.ts]"]
  node_sale_reads["Sale queries"]
  node_returns["Returns"]
  node_quotes["Quotes"]
  node_products["Products and stock"]
  node_purchasing["Purchase orders"]
  node_customers["Customers"]
  node_mechanics["Mechanic credit"]
  node_parked_sales["Parked sales"]
end

subgraph group_operations["Shop operations"]
  node_shifts["Cash drawer shifts"]
  node_review["Owner review"]
  node_reports["Reports"]
  node_settings["Settings and bootstrap"]
  node_sync_backup["Sync and backup"]
end

subgraph group_platform["Platform services"]
  node_idempotency["Idempotent writes"]
  node_devices["Device enrollment"]
  node_tenant_context["Tenant transactions<br/>[tenant.service.ts]"]
  node_postgres[("PostgreSQL tenant store")]
  node_redis[("Redis services")]
  node_queue["Background jobs"]
end

node_counter(("Counter staff"))

node_counter -->|"uses"| node_flutter
node_flutter -->|"calls HTTPS API"| node_api
node_api -.->|"guards tenant routes"| node_tenant_auth
node_tenant_auth -->|"caches tenant status"| node_redis
node_tenant_auth -.->|"establishes tenant scope"| node_tenant_context
node_sales -->|"creates sale"| node_sale_rules
node_sales -->|"queries sales"| node_sale_reads
node_sales -->|"sells quote"| node_quotes
node_sales -->|"runs idempotently"| node_idempotency
node_quotes -->|"runs idempotently"| node_idempotency
node_review -->|"runs idempotently"| node_idempotency
node_shifts -->|"runs idempotently"| node_idempotency
node_idempotency -->|"uses transaction context"| node_tenant_context
node_tenant_context -->|"runs tenant transactions"| node_postgres
node_idempotency -->|"uses cache accelerator"| node_redis
node_sales -.->|"sale affects stock"| node_products
node_purchasing -->|"receives stock"| node_products
node_returns -->|"refunds sales"| node_sales
node_mechanics -.->|"tracks credit sales"| node_sales
node_api -.->|"dispatches jobs"| node_queue
node_queue -.->|"processes tenant work"| node_postgres
node_api -->|"persists API data"| node_postgres
node_api -->|"serves enrollment"| node_devices
node_api -->|"serves customer routes"| node_customers
node_api -->|"serves parked sales"| node_parked_sales
node_api -->|"serves reports"| node_reports
node_api -->|"serves settings"| node_settings
node_api -->|"serves sync and backup"| node_sync_backup
node_api -->|"serves shifts"| node_shifts
node_api -->|"serves owner review"| node_review

click node_flutter "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/frontend"
click node_api "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src"
click node_tenant_auth "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/common/guards/tenant.guard.ts"
click node_idempotency "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/idempotency/idempotency.service.ts"
click node_sales "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sales.controller.ts"
click node_sale_rules "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sales.service.ts"
click node_sale_reads "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sale-reads.service.ts"
click node_returns "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/returns"
click node_quotes "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/quotes/quotes.controller.ts"
click node_products "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/products"
click node_purchasing "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/purchasing"
click node_customers "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/customers"
click node_mechanics "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/mechanics"
click node_parked_sales "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/parked-sales"
click node_shifts "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/shifts/shifts.controller.ts"
click node_review "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/review-items/review-items.controller.ts"
click node_reports "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/reports"
click node_settings "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/settings"
click node_sync_backup "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/sync"
click node_devices "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/devices"
click node_tenant_context "https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/common/database/tenant.service.ts"
click node_queue "https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/queue"

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_flutter toneBlue
class node_api,node_tenant_auth toneAmber
class node_sales,node_sale_rules,node_sale_reads,node_returns,node_quotes,node_products,node_purchasing,node_customers,node_mechanics,node_parked_sales toneMint
class node_shifts,node_review,node_reports,node_settings,node_sync_backup toneRose
class node_idempotency,node_devices,node_tenant_context,node_postgres,node_redis,node_queue,node_counter toneIndigo
```

## Components

### POS client

- [Flutter POS](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/frontend): `frontend`

### API access

- [NestJS API](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src): `server/src`
- [Tenant authentication](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/common/guards/tenant.guard.ts): `server/src/common/guards/tenant.guard.ts`

### Sales and stock

- [Sales checkout](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sales.controller.ts): `server/src/sales/sales.controller.ts`
- [Sale processing](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sales.service.ts): `server/src/sales/sales.service.ts`
- [Sale queries](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/sales/sale-reads.service.ts): `server/src/sales/sale-reads.service.ts`
- [Returns](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/returns): `server/src/returns`
- [Quotes](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/quotes/quotes.controller.ts): `server/src/quotes/quotes.controller.ts`
- [Products and stock](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/products): `server/src/products`
- [Purchase orders](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/purchasing): `server/src/purchasing`
- [Customers](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/customers): `server/src/customers`
- [Mechanic credit](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/mechanics): `server/src/mechanics`
- [Parked sales](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/parked-sales): `server/src/parked-sales`

### Shop operations

- [Cash drawer shifts](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/shifts/shifts.controller.ts): `server/src/shifts/shifts.controller.ts`
- [Owner review](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/review-items/review-items.controller.ts): `server/src/review-items/review-items.controller.ts`
- [Reports](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/reports): `server/src/reports`
- [Settings and bootstrap](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/settings): `server/src/settings`
- [Sync and backup](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/sync): `server/src/sync`

### Platform services

- [Idempotent writes](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/idempotency/idempotency.service.ts): `server/src/idempotency/idempotency.service.ts`
- [Device enrollment](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/devices): `server/src/devices`
- [Tenant transactions](https://github.com/nuimanlp/srisurart-pos-flutter/blob/main/server/src/common/database/tenant.service.ts): `server/src/common/database/tenant.service.ts`
- **PostgreSQL tenant store**
- **Redis services**
- [Background jobs](https://github.com/nuimanlp/srisurart-pos-flutter/tree/main/server/src/queue): `server/src/queue`

### Other components

- **Counter staff**

## Connections

- Counter staff → Flutter POS: uses (evidence: `README.md`)
- Flutter POS → NestJS API: calls HTTPS API (evidence: `README.md`)
- NestJS API → Tenant authentication: guards tenant routes (evidence: `server/src/review-items/review-items.controller.ts`)
- Tenant authentication → Redis services: caches tenant status (evidence: `server/src/common/guards/tenant.guard.ts`)
- Tenant authentication → Tenant transactions: establishes tenant scope
- Sales checkout → Sale processing: creates sale (evidence: `server/src/sales/sales.controller.ts`)
- Sales checkout → Sale queries: queries sales (evidence: `server/src/sales/sales.controller.ts`)
- Sales checkout → Quotes: sells quote (evidence: `server/src/sales/sales.controller.ts`)
- Sales checkout → Idempotent writes: runs idempotently (evidence: `server/src/sales/sales.controller.ts`)
- Quotes → Idempotent writes: runs idempotently (evidence: `server/src/quotes/quotes.controller.ts`)
- Owner review → Idempotent writes: runs idempotently (evidence: `server/src/review-items/review-items.controller.ts`)
- Cash drawer shifts → Idempotent writes: runs idempotently (evidence: `server/src/shifts/shifts.controller.ts`)
- Idempotent writes → Tenant transactions: uses transaction context (evidence: `server/src/idempotency/idempotency.service.ts`)
- Tenant transactions → PostgreSQL tenant store: runs tenant transactions (evidence: `README.md`)
- Idempotent writes → Redis services: uses cache accelerator (evidence: `server/src/idempotency/idempotency.service.ts`)
- Sales checkout → Products and stock: sale affects stock
- Purchase orders → Products and stock: receives stock (evidence: `README.md`)
- Returns → Sales checkout: refunds sales (evidence: `README.md`)
- Mechanic credit → Sales checkout: tracks credit sales
- NestJS API → Background jobs: dispatches jobs (evidence: `server/src/quotes/quotes.controller.ts`)
- Background jobs → PostgreSQL tenant store: processes tenant work
- NestJS API → PostgreSQL tenant store: persists API data (evidence: `README.md`)
- NestJS API → Device enrollment: serves enrollment (evidence: `README.md`)
- NestJS API → Customers: serves customer routes (evidence: `README.md`)
- NestJS API → Parked sales: serves parked sales (evidence: `README.md`)
- NestJS API → Reports: serves reports (evidence: `README.md`)
- NestJS API → Settings and bootstrap: serves settings (evidence: `README.md`)
- NestJS API → Sync and backup: serves sync and backup (evidence: `README.md`)
- NestJS API → Cash drawer shifts: serves shifts (evidence: `README.md`)
- NestJS API → Owner review: serves owner review (evidence: `README.md`)
