# john-michaelg135/api-pos architecture

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

- Interactive diagram: https://gitdiagram.com/john-michaelg135/api-pos
- Repository: https://github.com/john-michaelg135/api-pos

## Overview

This is a multi-location POS and commerce backend: staff and customer-facing APIs support catalog and stock operations, order entry and fulfillment, payments, refunds, reporting, and integrations with CRMS and SCMS. A typical order moves from an API request through order-entry logic, inventory and payment handling, and persistence; order management handles later approval and status changes. That workflow is visible in the source index, but most controller and service implementations were not excerpted, so uncertain links are shown as dashed.

Main entry points: [`Applications/Services/InventoryService.cs`](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/InventoryService.cs) (Stock operations), [`Infrastructures/Persistence/PosDbContext.cs`](https://github.com/john-michaelg135/api-pos/blob/main/Infrastructures/Persistence/PosDbContext.cs) (POS database), [`Applications/Services/OrderEntryService.cs`](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderEntryService.cs) (Order entry), [`Applications/Services/OrderManagementService.cs`](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderManagementService.cs) (Order fulfillment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["API and access"]
  node_order_api["Order entry API"]
  node_management_api["Order management API"]
  node_catalog_api["Product catalog API"]
  node_inventory_api["Inventory API"]
  node_auth["User context"]
end

subgraph group_commerce["Commerce operations"]
  node_order_entry["Order entry"]
  node_order_mgmt["Order fulfillment"]
  node_payments["Payment gateway<br/>[XenditService.cs]"]
  node_refunds["Refund handling<br/>[RefundService.cs]"]
  node_catalog["Product catalog"]
end

subgraph group_stock["Inventory and supply"]
  node_inventory["Stock operations"]
  node_scms["SCMS integration<br/>[ScmsApiClient.cs]"]
  node_transfers["Transfer receiving"]
end

subgraph group_insights["Customer and reporting"]
  node_analytics["Sales analytics"]
  node_dashboard["Owner dashboard"]
  node_crms_api["CRMS query API"]
  node_crms["Customer order queries"]
end

subgraph group_core["Domain and persistence"]
  node_db[("POS database<br/>[PosDbContext.cs]")]
  node_order_model["Order model<br/>[Order.cs]"]
  node_product_model["Product model<br/>[Product.cs]"]
  node_stock_model["Stock model<br/>[Stock.cs]"]
end

node_staff(("POS staff"))
node_customer(("Customer"))

node_staff -.->|"submits orders"| node_order_api
node_staff -.->|"manages orders"| node_management_api
node_customer -.->|"queries orders"| node_crms_api
node_order_api -.->|"dispatches to"| node_order_entry
node_management_api -->|"dispatches to"| node_order_mgmt
node_catalog_api -.->|"dispatches to"| node_catalog
node_inventory_api -.->|"dispatches to"| node_inventory
node_crms_api -->|"dispatches to"| node_crms
node_crms -->|"queries"| node_db
node_order_entry -->|"reads and writes"| node_db
node_order_entry -->|"uses stock service"| node_inventory
node_order_entry -->|"uses gateway"| node_payments
node_order_mgmt -->|"reads and writes"| node_db
node_order_mgmt -->|"uses stock service"| node_inventory
node_inventory -->|"reads and writes"| node_db
node_inventory -->|"calls client"| node_scms
node_inventory -->|"updates stock"| node_stock_model
node_transfers -.->|"receives stock"| node_inventory
node_order_entry -->|"creates orders"| node_order_model
node_db -->|"maps entity"| node_order_model
node_db -->|"maps entity"| node_product_model
node_auth -->|"resolves locations"| node_db

click node_order_api "https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/OrderEntryController.cs"
click node_management_api "https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/OrderManagementController.cs"
click node_catalog_api "https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/ProductCatalogController.cs"
click node_inventory_api "https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/InventoryController.cs"
click node_auth "https://github.com/john-michaelg135/api-pos/blob/main/Api/Middlewares/CurrentUserContext.cs"
click node_order_entry "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderEntryService.cs"
click node_order_mgmt "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderManagementService.cs"
click node_payments "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/XenditService.cs"
click node_refunds "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/RefundService.cs"
click node_catalog "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/ProductCatalogService.cs"
click node_inventory "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/InventoryService.cs"
click node_scms "https://github.com/john-michaelg135/api-pos/blob/main/Infrastructures/Externals/ScmsApiClient.cs"
click node_transfers "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/TransferReceivingService.cs"
click node_analytics "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/AnalyticsService.cs"
click node_dashboard "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/DashboardService.cs"
click node_crms_api "https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/CrmsQueryController.cs"
click node_crms "https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/CrmsQueryService.cs"
click node_db "https://github.com/john-michaelg135/api-pos/blob/main/Infrastructures/Persistence/PosDbContext.cs"
click node_order_model "https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Order.cs"
click node_product_model "https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Product.cs"
click node_stock_model "https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Stock.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_order_api,node_management_api,node_catalog_api,node_inventory_api,node_auth toneBlue
class node_order_entry,node_order_mgmt,node_payments,node_refunds,node_catalog toneAmber
class node_inventory,node_scms,node_transfers toneMint
class node_analytics,node_dashboard,node_crms_api,node_crms toneRose
class node_db,node_order_model,node_product_model,node_stock_model,node_staff,node_customer toneIndigo
```

## Components

### API and access

- [Order entry API](https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/OrderEntryController.cs): `Api/Controllers/OrderEntryController.cs`
- [Order management API](https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/OrderManagementController.cs): `Api/Controllers/OrderManagementController.cs`
- [Product catalog API](https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/ProductCatalogController.cs): `Api/Controllers/ProductCatalogController.cs`
- [Inventory API](https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/InventoryController.cs): `Api/Controllers/InventoryController.cs`
- [User context](https://github.com/john-michaelg135/api-pos/blob/main/Api/Middlewares/CurrentUserContext.cs): `Api/Middlewares/CurrentUserContext.cs`

### Commerce operations

- [Order entry](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderEntryService.cs): `Applications/Services/OrderEntryService.cs`
- [Order fulfillment](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/OrderManagementService.cs): `Applications/Services/OrderManagementService.cs`
- [Payment gateway](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/XenditService.cs): `Applications/Services/XenditService.cs`
- [Refund handling](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/RefundService.cs): `Applications/Services/RefundService.cs`
- [Product catalog](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/ProductCatalogService.cs): `Applications/Services/ProductCatalogService.cs`

### Inventory and supply

- [Stock operations](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/InventoryService.cs): `Applications/Services/InventoryService.cs`
- [SCMS integration](https://github.com/john-michaelg135/api-pos/blob/main/Infrastructures/Externals/ScmsApiClient.cs): `Infrastructures/Externals/ScmsApiClient.cs`
- [Transfer receiving](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/TransferReceivingService.cs): `Applications/Services/TransferReceivingService.cs`

### Customer and reporting

- [Sales analytics](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/AnalyticsService.cs): `Applications/Services/AnalyticsService.cs`
- [Owner dashboard](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/DashboardService.cs): `Applications/Services/DashboardService.cs`
- [CRMS query API](https://github.com/john-michaelg135/api-pos/blob/main/Api/Controllers/CrmsQueryController.cs): `Api/Controllers/CrmsQueryController.cs`
- [Customer order queries](https://github.com/john-michaelg135/api-pos/blob/main/Applications/Services/CrmsQueryService.cs): `Applications/Services/CrmsQueryService.cs`

### Domain and persistence

- [POS database](https://github.com/john-michaelg135/api-pos/blob/main/Infrastructures/Persistence/PosDbContext.cs): `Infrastructures/Persistence/PosDbContext.cs`
- [Order model](https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Order.cs): `Domains/Entities/Order.cs`
- [Product model](https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Product.cs): `Domains/Entities/Product.cs`
- [Stock model](https://github.com/john-michaelg135/api-pos/blob/main/Domains/Entities/Stock.cs): `Domains/Entities/Stock.cs`

### Other components

- **POS staff**
- **Customer**

## Connections

- POS staff → Order entry API: submits orders
- POS staff → Order management API: manages orders
- Customer → CRMS query API: queries orders
- Order entry API → Order entry: dispatches to
- Order management API → Order fulfillment: dispatches to (evidence: `Api/Controllers/OrderManagementController.cs`)
- Product catalog API → Product catalog: dispatches to
- Inventory API → Stock operations: dispatches to
- CRMS query API → Customer order queries: dispatches to (evidence: `Api/Controllers/CrmsQueryController.cs`)
- Customer order queries → POS database: queries (evidence: `Applications/Services/CrmsQueryService.cs`)
- Order entry → POS database: reads and writes (evidence: `Applications/Services/OrderEntryService.cs`)
- Order entry → Stock operations: uses stock service (evidence: `Applications/Services/OrderEntryService.cs`)
- Order entry → Payment gateway: uses gateway (evidence: `Applications/Services/OrderEntryService.cs`)
- Order fulfillment → POS database: reads and writes (evidence: `Applications/Services/OrderManagementService.cs`)
- Order fulfillment → Stock operations: uses stock service (evidence: `Applications/Services/OrderManagementService.cs`)
- Stock operations → POS database: reads and writes (evidence: `Applications/Services/InventoryService.cs`)
- Stock operations → SCMS integration: calls client (evidence: `Applications/Services/InventoryService.cs`)
- Stock operations → Stock model: updates stock (evidence: `Applications/Services/InventoryService.cs`)
- Transfer receiving → Stock operations: receives stock
- Order entry → Order model: creates orders (evidence: `Applications/Services/OrderEntryService.cs`)
- POS database → Order model: maps entity (evidence: `Infrastructures/Persistence/PosDbContext.cs`)
- POS database → Product model: maps entity (evidence: `Infrastructures/Persistence/PosDbContext.cs`)
- User context → POS database: resolves locations (evidence: `Api/Middlewares/CurrentUserContext.cs`)
