# jomsq/pos architecture

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

- Interactive diagram: https://gitdiagram.com/jomsq/pos
- Repository: https://github.com/jomsq/pos

## Overview

This is a multi-client point-of-sale system: browser and desktop interfaces support counter sales and back-office work, while an ASP.NET API and application services handle business operations. Major domain areas include catalog, checkout, inventory/purchasing, shifts, reports, and e-services; offline sales and synchronization are also explicit subsystems. The API configures application and infrastructure services, authentication, and controller routing. The excerpts do not show most UI-to-API or controller-to-service calls, so those relationships are omitted or marked unverified rather than inferred as observed.

Main entry points: [`src/Infrastructure/Persistence/PosDbContext.cs`](https://github.com/jomsq/pos/blob/main/src/Infrastructure/Persistence/PosDbContext.cs) (Database context), [`src/Api/Program.cs`](https://github.com/jomsq/pos/blob/main/src/Api/Program.cs) (HTTP API), [`src/UI/Services/Api/ApiClients.cs`](https://github.com/jomsq/pos/blob/main/src/UI/Services/Api/ApiClients.cs) (API clients), [`src/Web/Program.cs`](https://github.com/jomsq/pos/blob/main/src/Web/Program.cs) (Browser app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["POS clients"]
  node_webapp["Browser app<br/>[Program.cs]"]
  node_desktopapp["Desktop app<br/>[MauiProgram.cs]"]
  node_checkoutui["Checkout UI<br/>[Checkout.razor.cs]"]
  node_eservicesui["E-services UI"]
  node_apiclients["API clients<br/>[ApiClients.cs]"]
  node_authui["Client auth<br/>[AuthHandler.cs]"]
end

subgraph group_api["API and identity"]
  node_api["HTTP API<br/>[Program.cs]"]
  node_auth["Authentication<br/>[AuthService.cs]"]
end

subgraph group_operations["Store operations"]
  node_catalog["Product catalog<br/>[ProductService.cs]"]
  node_productimport["Catalog import"]
  node_sales["Sales and refunds<br/>[SaleService.cs]"]
  node_inventory["Inventory and receiving"]
  node_purchasing["Purchase orders"]
  node_eshop["E-services<br/>[EServiceService.cs]"]
  node_shifts["Shifts and closing<br/>[ZReadingService.cs]"]
  node_reports["Reporting<br/>[ReportService.cs]"]
  node_pricing["Pricing math<br/>[CartCalculator.cs]"]
end

subgraph group_offline["Offline operations"]
  node_offline["Offline sales<br/>[OfflineSales.cs]"]
  node_sync["Sync engine<br/>[SyncEngine.cs]"]
  node_localstore[("Local store")]
end

subgraph group_persistence["Persistence and domain"]
  node_dbcontext[("Database context<br/>[PosDbContext.cs]")]
  node_entities["POS entities"]
  node_seed["Initial data<br/>[DatabaseSeeder.cs]"]
end

node_cashier(("Cashier / staff"))

node_cashier -.->|"uses"| node_webapp
node_cashier -.->|"uses"| node_desktopapp
node_webapp -.->|"calls"| node_api
node_desktopapp -.->|"calls"| node_api
node_webapp -->|"configures UI"| node_apiclients
node_checkoutui -.->|"uses"| node_apiclients
node_eservicesui -.->|"uses"| node_apiclients
node_authui -.->|"authenticates requests"| node_apiclients
node_api -.->|"routes auth"| node_auth
node_api -->|"initializes database"| node_dbcontext
node_api -->|"runs seeding"| node_seed
node_catalog -->|"uses data context"| node_dbcontext
node_productimport -->|"uses product rules"| node_catalog
node_sales -->|"calculates cart"| node_pricing
node_sales -->|"uses product service"| node_catalog
node_inventory -->|"uses purchase orders"| node_purchasing
node_inventory -->|"uses cost math"| node_pricing
node_sync -->|"reads and writes"| node_localstore
node_sync -->|"updates offline state"| node_offline
node_eshop -.->|"persists transactions"| node_entities
node_shifts -.->|"uses data context"| node_dbcontext
node_reports -.->|"uses data context"| node_dbcontext
node_dbcontext -.->|"maps entities"| node_entities
node_seed -->|"seeds records"| node_dbcontext

click node_webapp "https://github.com/jomsq/pos/blob/main/src/Web/Program.cs"
click node_desktopapp "https://github.com/jomsq/pos/blob/main/src/Desktop/MauiProgram.cs"
click node_checkoutui "https://github.com/jomsq/pos/blob/main/src/UI/Features/Checkout/Checkout.razor.cs"
click node_eservicesui "https://github.com/jomsq/pos/blob/main/src/UI/Features/EServices/EServicesPage.razor.cs"
click node_apiclients "https://github.com/jomsq/pos/blob/main/src/UI/Services/Api/ApiClients.cs"
click node_authui "https://github.com/jomsq/pos/blob/main/src/UI/Services/Auth/AuthHandler.cs"
click node_api "https://github.com/jomsq/pos/blob/main/src/Api/Program.cs"
click node_auth "https://github.com/jomsq/pos/blob/main/src/Application/Auth/AuthService.cs"
click node_catalog "https://github.com/jomsq/pos/blob/main/src/Application/Catalog/ProductService.cs"
click node_productimport "https://github.com/jomsq/pos/blob/main/src/Application/Catalog/ProductImportService.cs"
click node_sales "https://github.com/jomsq/pos/blob/main/src/Application/Sales/SaleService.cs"
click node_inventory "https://github.com/jomsq/pos/blob/main/src/Application/Inventory/StockReceiptService.cs"
click node_purchasing "https://github.com/jomsq/pos/blob/main/src/Application/Purchasing/PurchaseOrderService.cs"
click node_eshop "https://github.com/jomsq/pos/blob/main/src/Application/EServices/EServiceService.cs"
click node_shifts "https://github.com/jomsq/pos/blob/main/src/Application/Shifts/ZReadingService.cs"
click node_reports "https://github.com/jomsq/pos/blob/main/src/Application/Reports/ReportService.cs"
click node_pricing "https://github.com/jomsq/pos/blob/main/src/Pricing/CartCalculator.cs"
click node_offline "https://github.com/jomsq/pos/blob/main/src/Offline/OfflineSales.cs"
click node_sync "https://github.com/jomsq/pos/blob/main/src/Offline/SyncEngine.cs"
click node_localstore "https://github.com/jomsq/pos/blob/main/src/Offline/SqliteLocalStore.cs"
click node_dbcontext "https://github.com/jomsq/pos/blob/main/src/Infrastructure/Persistence/PosDbContext.cs"
click node_entities "https://github.com/jomsq/pos/tree/main/src/Domain/Entities"
click node_seed "https://github.com/jomsq/pos/blob/main/src/Infrastructure/Seed/DatabaseSeeder.cs"

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_webapp,node_desktopapp,node_checkoutui,node_eservicesui,node_apiclients,node_authui toneBlue
class node_api,node_auth toneAmber
class node_catalog,node_productimport,node_sales,node_inventory,node_purchasing,node_eshop,node_shifts,node_reports,node_pricing toneMint
class node_offline,node_sync,node_localstore toneRose
class node_dbcontext,node_entities,node_seed,node_cashier toneIndigo
```

## Components

### POS clients

- [Browser app](https://github.com/jomsq/pos/blob/main/src/Web/Program.cs): `src/Web/Program.cs`
- [Desktop app](https://github.com/jomsq/pos/blob/main/src/Desktop/MauiProgram.cs): `src/Desktop/MauiProgram.cs`
- [Checkout UI](https://github.com/jomsq/pos/blob/main/src/UI/Features/Checkout/Checkout.razor.cs): `src/UI/Features/Checkout/Checkout.razor.cs`
- [E-services UI](https://github.com/jomsq/pos/blob/main/src/UI/Features/EServices/EServicesPage.razor.cs): `src/UI/Features/EServices/EServicesPage.razor.cs`
- [API clients](https://github.com/jomsq/pos/blob/main/src/UI/Services/Api/ApiClients.cs): `src/UI/Services/Api/ApiClients.cs`
- [Client auth](https://github.com/jomsq/pos/blob/main/src/UI/Services/Auth/AuthHandler.cs): `src/UI/Services/Auth/AuthHandler.cs`

### API and identity

- [HTTP API](https://github.com/jomsq/pos/blob/main/src/Api/Program.cs): `src/Api/Program.cs`
- [Authentication](https://github.com/jomsq/pos/blob/main/src/Application/Auth/AuthService.cs): `src/Application/Auth/AuthService.cs`

### Store operations

- [Product catalog](https://github.com/jomsq/pos/blob/main/src/Application/Catalog/ProductService.cs): `src/Application/Catalog/ProductService.cs`
- [Catalog import](https://github.com/jomsq/pos/blob/main/src/Application/Catalog/ProductImportService.cs): `src/Application/Catalog/ProductImportService.cs`
- [Sales and refunds](https://github.com/jomsq/pos/blob/main/src/Application/Sales/SaleService.cs): `src/Application/Sales/SaleService.cs`
- [Inventory and receiving](https://github.com/jomsq/pos/blob/main/src/Application/Inventory/StockReceiptService.cs): `src/Application/Inventory/StockReceiptService.cs`
- [Purchase orders](https://github.com/jomsq/pos/blob/main/src/Application/Purchasing/PurchaseOrderService.cs): `src/Application/Purchasing/PurchaseOrderService.cs`
- [E-services](https://github.com/jomsq/pos/blob/main/src/Application/EServices/EServiceService.cs): `src/Application/EServices/EServiceService.cs`
- [Shifts and closing](https://github.com/jomsq/pos/blob/main/src/Application/Shifts/ZReadingService.cs): `src/Application/Shifts/ZReadingService.cs`
- [Reporting](https://github.com/jomsq/pos/blob/main/src/Application/Reports/ReportService.cs): `src/Application/Reports/ReportService.cs`
- [Pricing math](https://github.com/jomsq/pos/blob/main/src/Pricing/CartCalculator.cs): `src/Pricing/CartCalculator.cs`

### Offline operations

- [Offline sales](https://github.com/jomsq/pos/blob/main/src/Offline/OfflineSales.cs): `src/Offline/OfflineSales.cs`
- [Sync engine](https://github.com/jomsq/pos/blob/main/src/Offline/SyncEngine.cs): `src/Offline/SyncEngine.cs`
- [Local store](https://github.com/jomsq/pos/blob/main/src/Offline/SqliteLocalStore.cs): `src/Offline/SqliteLocalStore.cs`

### Persistence and domain

- [Database context](https://github.com/jomsq/pos/blob/main/src/Infrastructure/Persistence/PosDbContext.cs): `src/Infrastructure/Persistence/PosDbContext.cs`
- [POS entities](https://github.com/jomsq/pos/tree/main/src/Domain/Entities): `src/Domain/Entities`
- [Initial data](https://github.com/jomsq/pos/blob/main/src/Infrastructure/Seed/DatabaseSeeder.cs): `src/Infrastructure/Seed/DatabaseSeeder.cs`

### Other components

- **Cashier / staff**

## Connections

- Cashier / staff → Browser app: uses
- Cashier / staff → Desktop app: uses
- Browser app → HTTP API: calls
- Desktop app → HTTP API: calls
- Browser app → API clients: configures UI (evidence: `src/Web/Program.cs`)
- Checkout UI → API clients: uses
- E-services UI → API clients: uses
- Client auth → API clients: authenticates requests
- HTTP API → Authentication: routes auth
- HTTP API → Database context: initializes database (evidence: `src/Api/Program.cs`)
- HTTP API → Initial data: runs seeding (evidence: `src/Api/Program.cs`)
- Product catalog → Database context: uses data context (evidence: `src/Application/Catalog/ProductService.cs`)
- Catalog import → Product catalog: uses product rules (evidence: `src/Application/Catalog/ProductImportService.cs`)
- Sales and refunds → Pricing math: calculates cart (evidence: `src/Application/Sales/SaleService.cs`)
- Sales and refunds → Product catalog: uses product service (evidence: `src/Application/Sales/SaleService.cs`)
- Inventory and receiving → Purchase orders: uses purchase orders (evidence: `src/Application/Inventory/StockReceiptService.cs`)
- Inventory and receiving → Pricing math: uses cost math (evidence: `src/Application/Inventory/StockReceiptService.cs`)
- Sync engine → Local store: reads and writes (evidence: `src/Offline/SyncEngine.cs`)
- Sync engine → Offline sales: updates offline state (evidence: `src/Offline/SyncEngine.cs`)
- E-services → POS entities: persists transactions
- Shifts and closing → Database context: uses data context
- Reporting → Database context: uses data context
- Database context → POS entities: maps entities
- Initial data → Database context: seeds records (evidence: `src/Infrastructure/Seed/DatabaseSeeder.cs`)
