# michaelngogoyo/nexus-pos architecture

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

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

## Overview

This is a restaurant and retail point-of-sale platform with React POS and admin workspaces, a Spring Boot REST backend, and a separate Java desktop client with offline synchronization. The main workflow runs from cashier checkout through sales/order processing, with related kitchen, floor, shift, inventory, procurement, and reporting capabilities. Backend persistence and the desktop sync path are included as internal layers. Some subsystems are represented by directory paths because their source was not sampled; those links are left unasserted where the excerpts do not establish them.

Main entry points: [`posFrontend/src/services/api.js`](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/services/api.js) (API Client), [`posBackend/src/main/java/com/pos/controller`](https://github.com/michaelngogoyo/nexus-pos/tree/master/posBackend/src/main/java/com/pos/controller) (REST Controllers), [`POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java) (Sync Service), [`posBackend/src/main/java/com/pos/service/impl/SalesService.java`](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/SalesService.java) (Sales Processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web Workspaces"]
  node_app["App Routing<br/>[App.jsx]"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_operations["POS Operations"]
  node_pos_checkout["Touch Checkout<br/>[POSCheckout.jsx]"]
  node_pos_orders["Order Management<br/>[POSOrders.jsx]"]
  node_kitchen["Kitchen Display<br/>[POSKitchen.jsx]"]
  node_floor["Tables and Reservations<br/>[POSTables.jsx]"]
  node_shift["Shift Management<br/>[POSShift.jsx]"]
end

subgraph group_management["Business Management"]
  node_admin["Admin Workspace<br/>[AdminLayout.jsx]"]
  node_catalog["Catalog and Inventory<br/>[Products.jsx]"]
  node_finance["Purchases and Finance<br/>[Purchases.jsx]"]
  node_reports["Analytics and Reports<br/>[Reports.jsx]"]
  node_audit["Audit Management<br/>[AuditLog.jsx]"]
end

subgraph group_backend["Backend Services"]
  node_backend_api["REST Controllers"]
  node_sales_service["Sales Processing<br/>[SalesService.java]"]
  node_restaurant_orders["Restaurant Orders"]
  node_procurement["Purchase Orders"]
  node_report_service["Report Generation<br/>[ReportService.java]"]
  node_audit_service["Audit Logging<br/>[AuditService.java]"]
  node_product_store[("Product Repository")]
  node_stock_store[("Stock Movements")]
end

subgraph group_desktop["Desktop Offline"]
  node_desktop_app["Desktop Application"]
  node_desktop_auth["Desktop Authentication<br/>[AuthService.java]"]
  node_module_service["Offline Modules<br/>[ModuleService.java]"]
  node_local_store[("Local Entity Store")]
  node_sync_queue[("Sync Queue")]
  node_sync_service["Sync Service<br/>[SyncService.java]"]
  node_network_client["Network Client<br/>[NetworkClient.java]"]
  node_session[("Desktop Session<br/>[SessionStore.java]")]
end

node_staff(("POS Staff"))
node_keycloak{{"Keycloak"}}
node_minio[("MinIO Storage")]

node_staff -->|"uses"| node_app
node_app -->|"routes to"| node_pos_checkout
node_app -->|"routes to"| node_admin
node_pos_checkout -.->|"requests data"| node_api_client
node_pos_orders -.->|"requests data"| node_api_client
node_kitchen -.->|"requests data"| node_api_client
node_floor -.->|"requests data"| node_api_client
node_shift -.->|"requests data"| node_api_client
node_catalog -.->|"requests data"| node_api_client
node_finance -.->|"requests data"| node_api_client
node_reports -.->|"requests data"| node_api_client
node_api_client -->|"calls REST API"| node_backend_api
node_backend_api -.->|"dispatches"| node_sales_service
node_backend_api -.->|"dispatches"| node_restaurant_orders
node_backend_api -.->|"dispatches"| node_procurement
node_backend_api -.->|"dispatches"| node_report_service
node_sales_service -->|"reads products"| node_product_store
node_sales_service -.->|"records movements"| node_stock_store
node_restaurant_orders -->|"updates stock"| node_product_store
node_restaurant_orders -->|"records movements"| node_stock_store
node_procurement -->|"receives products"| node_product_store
node_procurement -->|"records movements"| node_stock_store
node_reports -.->|"requests reports"| node_report_service
node_report_service -->|"queries analytics"| node_product_store
node_audit -.->|"uses audit API"| node_backend_api
node_sales_service -.->|"logs actions"| node_audit_service
node_restaurant_orders -->|"logs actions"| node_audit_service
node_procurement -->|"logs actions"| node_audit_service
node_admin -.->|"authenticates with"| node_keycloak
node_backend_api -.->|"stores images"| node_minio
node_staff -.->|"uses"| node_desktop_app
node_desktop_app -.->|"authenticates through"| node_desktop_auth
node_desktop_auth -->|"requests tokens"| node_network_client
node_desktop_auth -->|"stores session"| node_session
node_desktop_auth -->|"caches account"| node_local_store
node_module_service -->|"fetches remotely"| node_network_client
node_module_service -->|"caches entities"| node_local_store
node_module_service -->|"queues offline writes"| node_sync_queue
node_sync_service -->|"reads and clears"| node_sync_queue
node_sync_service -->|"marks clean"| node_local_store
node_sync_service -->|"sends queued writes"| node_network_client
node_sync_service -->|"reads token"| node_session

click node_app "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/App.jsx"
click node_pos_checkout "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/checkout/POSCheckout.jsx"
click node_pos_orders "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/orders/POSOrders.jsx"
click node_kitchen "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/kitchen/POSKitchen.jsx"
click node_floor "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/tables/POSTables.jsx"
click node_shift "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/shift/POSShift.jsx"
click node_admin "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/admin/AdminLayout.jsx"
click node_catalog "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/product/Products.jsx"
click node_finance "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/finance/Purchases.jsx"
click node_reports "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/reports/Reports.jsx"
click node_audit "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/admin/AuditLog.jsx"
click node_api_client "https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/services/api.js"
click node_backend_api "https://github.com/michaelngogoyo/nexus-pos/tree/master/posBackend/src/main/java/com/pos/controller"
click node_sales_service "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/SalesService.java"
click node_restaurant_orders "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/RestaurantOrderService.java"
click node_procurement "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/PurchaseOrderService.java"
click node_report_service "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/ReportService.java"
click node_audit_service "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/AuditService.java"
click node_product_store "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/repository/ProductRepository.java"
click node_stock_store "https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/repository/StockMovementRepository.java"
click node_desktop_app "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/PosDesktopApplication.java"
click node_desktop_auth "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java"
click node_module_service "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java"
click node_local_store "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/LocalEntityStore.java"
click node_sync_queue "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/SyncQueueStore.java"
click node_sync_service "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java"
click node_network_client "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/NetworkClient.java"
click node_session "https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/auth/SessionStore.java"

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_app,node_api_client toneBlue
class node_pos_checkout,node_pos_orders,node_kitchen,node_floor,node_shift,node_minio toneAmber
class node_admin,node_catalog,node_finance,node_reports,node_audit toneMint
class node_backend_api,node_sales_service,node_restaurant_orders,node_procurement,node_report_service,node_audit_service,node_product_store,node_stock_store toneRose
class node_desktop_app,node_desktop_auth,node_module_service,node_local_store,node_sync_queue,node_sync_service,node_network_client,node_session,node_staff,node_keycloak toneIndigo
```

## Components

### Web Workspaces

- [App Routing](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/App.jsx): `posFrontend/src/App.jsx`
- [API Client](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/services/api.js): `posFrontend/src/services/api.js`

### POS Operations

- [Touch Checkout](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/checkout/POSCheckout.jsx): `posFrontend/src/pos/checkout/POSCheckout.jsx`
- [Order Management](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/orders/POSOrders.jsx): `posFrontend/src/pos/orders/POSOrders.jsx`
- [Kitchen Display](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/kitchen/POSKitchen.jsx): `posFrontend/src/pos/kitchen/POSKitchen.jsx`
- [Tables and Reservations](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/tables/POSTables.jsx): `posFrontend/src/pos/tables/POSTables.jsx`
- [Shift Management](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pos/shift/POSShift.jsx): `posFrontend/src/pos/shift/POSShift.jsx`

### Business Management

- [Admin Workspace](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/admin/AdminLayout.jsx): `posFrontend/src/admin/AdminLayout.jsx`
- [Catalog and Inventory](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/product/Products.jsx): `posFrontend/src/pages/product/Products.jsx`
- [Purchases and Finance](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/finance/Purchases.jsx): `posFrontend/src/pages/finance/Purchases.jsx`
- [Analytics and Reports](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/reports/Reports.jsx): `posFrontend/src/pages/reports/Reports.jsx`
- [Audit Management](https://github.com/michaelngogoyo/nexus-pos/blob/master/posFrontend/src/pages/admin/AuditLog.jsx): `posFrontend/src/pages/admin/AuditLog.jsx`

### Backend Services

- [REST Controllers](https://github.com/michaelngogoyo/nexus-pos/tree/master/posBackend/src/main/java/com/pos/controller): `posBackend/src/main/java/com/pos/controller`
- [Sales Processing](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/SalesService.java): `posBackend/src/main/java/com/pos/service/impl/SalesService.java`
- [Restaurant Orders](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/RestaurantOrderService.java): `posBackend/src/main/java/com/pos/service/RestaurantOrderService.java`
- [Purchase Orders](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/PurchaseOrderService.java): `posBackend/src/main/java/com/pos/service/PurchaseOrderService.java`
- [Report Generation](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/ReportService.java): `posBackend/src/main/java/com/pos/service/impl/ReportService.java`
- [Audit Logging](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/service/impl/AuditService.java): `posBackend/src/main/java/com/pos/service/impl/AuditService.java`
- [Product Repository](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/repository/ProductRepository.java): `posBackend/src/main/java/com/pos/repository/ProductRepository.java`
- [Stock Movements](https://github.com/michaelngogoyo/nexus-pos/blob/master/posBackend/src/main/java/com/pos/repository/StockMovementRepository.java): `posBackend/src/main/java/com/pos/repository/StockMovementRepository.java`

### Desktop Offline

- [Desktop Application](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/PosDesktopApplication.java): `POS_Desktop/src/main/java/com/pos/desktop/PosDesktopApplication.java`
- [Desktop Authentication](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java): `POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java`
- [Offline Modules](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java): `POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java`
- [Local Entity Store](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/LocalEntityStore.java): `POS_Desktop/src/main/java/com/pos/desktop/core/LocalEntityStore.java`
- [Sync Queue](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/SyncQueueStore.java): `POS_Desktop/src/main/java/com/pos/desktop/core/SyncQueueStore.java`
- [Sync Service](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java): `POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`
- [Network Client](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/core/NetworkClient.java): `POS_Desktop/src/main/java/com/pos/desktop/core/NetworkClient.java`
- [Desktop Session](https://github.com/michaelngogoyo/nexus-pos/blob/master/POS_Desktop/src/main/java/com/pos/desktop/auth/SessionStore.java): `POS_Desktop/src/main/java/com/pos/desktop/auth/SessionStore.java`

### Other components

- **POS Staff**
- **Keycloak**
- **MinIO Storage**

## Connections

- POS Staff → App Routing: uses
- App Routing → Touch Checkout: routes to (evidence: `posFrontend/src/App.jsx`)
- App Routing → Admin Workspace: routes to (evidence: `posFrontend/src/App.jsx`)
- Touch Checkout → API Client: requests data
- Order Management → API Client: requests data
- Kitchen Display → API Client: requests data
- Tables and Reservations → API Client: requests data
- Shift Management → API Client: requests data
- Catalog and Inventory → API Client: requests data
- Purchases and Finance → API Client: requests data
- Analytics and Reports → API Client: requests data
- API Client → REST Controllers: calls REST API
- REST Controllers → Sales Processing: dispatches
- REST Controllers → Restaurant Orders: dispatches
- REST Controllers → Purchase Orders: dispatches
- REST Controllers → Report Generation: dispatches
- Sales Processing → Product Repository: reads products (evidence: `posBackend/src/main/java/com/pos/service/impl/SalesService.java`)
- Sales Processing → Stock Movements: records movements (evidence: `posBackend/src/main/java/com/pos/service/impl/SalesService.java`)
- Restaurant Orders → Product Repository: updates stock (evidence: `posBackend/src/main/java/com/pos/service/RestaurantOrderService.java`)
- Restaurant Orders → Stock Movements: records movements (evidence: `posBackend/src/main/java/com/pos/service/RestaurantOrderService.java`)
- Purchase Orders → Product Repository: receives products (evidence: `posBackend/src/main/java/com/pos/service/PurchaseOrderService.java`)
- Purchase Orders → Stock Movements: records movements (evidence: `posBackend/src/main/java/com/pos/service/PurchaseOrderService.java`)
- Analytics and Reports → Report Generation: requests reports
- Report Generation → Product Repository: queries analytics (evidence: `posBackend/src/main/java/com/pos/service/impl/ReportService.java`)
- Audit Management → REST Controllers: uses audit API
- Sales Processing → Audit Logging: logs actions (evidence: `posBackend/src/main/java/com/pos/service/impl/SalesService.java`)
- Restaurant Orders → Audit Logging: logs actions (evidence: `posBackend/src/main/java/com/pos/service/RestaurantOrderService.java`)
- Purchase Orders → Audit Logging: logs actions (evidence: `posBackend/src/main/java/com/pos/service/PurchaseOrderService.java`)
- Admin Workspace → Keycloak: authenticates with
- REST Controllers → MinIO Storage: stores images
- POS Staff → Desktop Application: uses
- Desktop Application → Desktop Authentication: authenticates through
- Desktop Authentication → Network Client: requests tokens (evidence: `POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java`)
- Desktop Authentication → Desktop Session: stores session (evidence: `POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java`)
- Desktop Authentication → Local Entity Store: caches account (evidence: `POS_Desktop/src/main/java/com/pos/desktop/auth/AuthService.java`)
- Offline Modules → Network Client: fetches remotely (evidence: `POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java`)
- Offline Modules → Local Entity Store: caches entities (evidence: `POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java`)
- Offline Modules → Sync Queue: queues offline writes (evidence: `POS_Desktop/src/main/java/com/pos/desktop/service/ModuleService.java`)
- Sync Service → Sync Queue: reads and clears (evidence: `POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`)
- Sync Service → Local Entity Store: marks clean (evidence: `POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`)
- Sync Service → Network Client: sends queued writes (evidence: `POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`)
- Sync Service → Desktop Session: reads token (evidence: `POS_Desktop/src/main/java/com/pos/desktop/core/SyncService.java`)
