# trannamkhanh/retailsync architecture

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

- Interactive diagram: https://gitdiagram.com/trannamkhanh/retailsync
- Repository: https://github.com/trannamkhanh/retailsync

## Overview

RetailSync is a regional retail middleware system: POS terminals submit events, the middleware validates and records them, supports live inventory and operational recommendations, then aggregates and syncs batches to HQ. The repository also includes a simulated HQ service and two Windows demo clients. The main app wiring and POS event path are excerpted; many feature modules are indexed but unsampled, so their internal call edges are omitted or marked unverified.

Main entry points: [`middleware/app/main.py`](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/main.py) (Middleware app), [`middleware/app/api/pos.py`](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/pos.py) (POS event API), [`middleware/app/jobs/scheduler.py`](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/jobs/scheduler.py) (Job scheduler), [`hq-demo/app/main.py`](https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/main.py) (HQ demo API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_middleware["Retail Middleware"]
  node_main["Middleware app<br/>[main.py]"]
  node_pos_api["POS event API<br/>[pos.py]"]
  node_event_processing["Event processing<br/>[pos_events.py]"]
  node_db_access["Database access<br/>[db.py]"]
  node_domain_models["Retail data models<br/>[models.py]"]
  node_inventory_api["Inventory API<br/>[inventory.py]"]
  node_inventory_service["Inventory service<br/>[inventory.py]"]
  node_product_api["Product API<br/>[products.py]"]
end

subgraph group_analytics["Operations Insights"]
  node_near_expiry["Expiry alerts<br/>[near_expiry.py]"]
  node_forecast["Forecasting<br/>[forecast.py]"]
  node_guardrails["Guardrail recommendations<br/>[guardrails.py]"]
  node_aggregation["Sales aggregation<br/>[aggregation.py]"]
  node_scheduler["Job scheduler<br/>[scheduler.py]"]
  node_sync_sender["HQ sync sender<br/>[sync_sender.py]"]
end

subgraph group_hq["HQ Demo"]
  node_hq_client["HQ client<br/>[hq_client.py]"]
  node_hq_service["HQ demo API<br/>[main.py]"]
  node_hq_batch["Batch application<br/>[service.py]"]
  node_hq_database[("HQ database<br/>[db.py]")]
end

subgraph group_clients["Demo Clients"]
  node_pos_demo_ui["POS demo UI<br/>[MainForm.cs]"]
  node_pos_demo_client["POS terminal client<br/>[TerminalClient.cs]"]
  node_console_ui["Presenter console<br/>[MainForm.cs]"]
  node_console_api["Console API client<br/>[DemoApiClient.cs]"]
end

node_pos_actor(("POS terminal"))
node_staff_actor(("Staff and admin"))

node_pos_actor -->|"operates"| node_pos_demo_ui
node_pos_demo_ui -.->|"sends events"| node_pos_demo_client
node_pos_demo_client -.->|"posts events"| node_pos_api
node_pos_actor -->|"submits events"| node_pos_api
node_staff_actor -->|"uses services"| node_main
node_main -->|"registers router"| node_pos_api
node_main -->|"registers router"| node_inventory_api
node_main -->|"registers router"| node_product_api
node_main -->|"starts scheduler"| node_scheduler
node_pos_api -->|"processes event"| node_event_processing
node_pos_api -->|"gets session"| node_db_access
node_pos_api -->|"checks terminal"| node_domain_models
node_inventory_api -.->|"reads inventory"| node_inventory_service
node_scheduler -.->|"runs jobs"| node_aggregation
node_scheduler -.->|"runs jobs"| node_forecast
node_scheduler -.->|"runs jobs"| node_near_expiry
node_scheduler -.->|"runs jobs"| node_sync_sender
node_sync_sender -.->|"sends batches"| node_hq_client
node_hq_client -.->|"syncs batches"| node_hq_service
node_hq_service -->|"applies batch"| node_hq_batch
node_hq_service -->|"reads batches"| node_hq_database
node_hq_batch -->|"updates totals"| node_hq_database
node_console_ui -.->|"requests data"| node_console_api
node_console_api -.->|"calls API"| node_main

click node_main "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/main.py"
click node_pos_api "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/pos.py"
click node_event_processing "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/pos_events.py"
click node_db_access "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/core/db.py"
click node_domain_models "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/domain/models.py"
click node_inventory_api "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/inventory.py"
click node_inventory_service "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/inventory.py"
click node_product_api "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/products.py"
click node_near_expiry "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/near_expiry.py"
click node_forecast "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/forecast.py"
click node_guardrails "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/guardrails.py"
click node_aggregation "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/jobs/aggregation.py"
click node_scheduler "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/jobs/scheduler.py"
click node_sync_sender "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/sync_sender.py"
click node_hq_client "https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/integration/hq_client.py"
click node_hq_service "https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/main.py"
click node_hq_batch "https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/service.py"
click node_hq_database "https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/db.py"
click node_pos_demo_ui "https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-pos/DemoPos/UI/MainForm.cs"
click node_pos_demo_client "https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-pos/DemoPos/Services/TerminalClient.cs"
click node_console_ui "https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-console/DemoConsole/UI/MainForm.cs"
click node_console_api "https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-console/DemoConsole/Services/DemoApiClient.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_main,node_pos_api,node_event_processing,node_db_access,node_domain_models,node_inventory_api,node_inventory_service,node_product_api toneBlue
class node_near_expiry,node_forecast,node_guardrails,node_aggregation,node_scheduler,node_sync_sender toneAmber
class node_hq_client,node_hq_service,node_hq_batch,node_hq_database toneMint
class node_pos_demo_ui,node_pos_demo_client,node_console_ui,node_console_api toneRose
class node_pos_actor,node_staff_actor toneIndigo
```

## Components

### Retail Middleware

- [Middleware app](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/main.py): `middleware/app/main.py`
- [POS event API](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/pos.py): `middleware/app/api/pos.py`
- [Event processing](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/pos_events.py): `middleware/app/services/pos_events.py`
- [Database access](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/core/db.py): `middleware/app/core/db.py`
- [Retail data models](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/domain/models.py): `middleware/app/domain/models.py`
- [Inventory API](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/inventory.py): `middleware/app/api/inventory.py`
- [Inventory service](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/inventory.py): `middleware/app/services/inventory.py`
- [Product API](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/api/products.py): `middleware/app/api/products.py`

### Operations Insights

- [Expiry alerts](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/near_expiry.py): `middleware/app/services/near_expiry.py`
- [Forecasting](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/forecast.py): `middleware/app/services/forecast.py`
- [Guardrail recommendations](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/guardrails.py): `middleware/app/services/guardrails.py`
- [Sales aggregation](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/jobs/aggregation.py): `middleware/app/jobs/aggregation.py`
- [Job scheduler](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/jobs/scheduler.py): `middleware/app/jobs/scheduler.py`
- [HQ sync sender](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/services/sync_sender.py): `middleware/app/services/sync_sender.py`

### HQ Demo

- [HQ client](https://github.com/trannamkhanh/retailsync/blob/main/middleware/app/integration/hq_client.py): `middleware/app/integration/hq_client.py`
- [HQ demo API](https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/main.py): `hq-demo/app/main.py`
- [Batch application](https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/service.py): `hq-demo/app/service.py`
- [HQ database](https://github.com/trannamkhanh/retailsync/blob/main/hq-demo/app/db.py): `hq-demo/app/db.py`

### Demo Clients

- [POS demo UI](https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-pos/DemoPos/UI/MainForm.cs): `clients/demo-pos/DemoPos/UI/MainForm.cs`
- [POS terminal client](https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-pos/DemoPos/Services/TerminalClient.cs): `clients/demo-pos/DemoPos/Services/TerminalClient.cs`
- [Presenter console](https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-console/DemoConsole/UI/MainForm.cs): `clients/demo-console/DemoConsole/UI/MainForm.cs`
- [Console API client](https://github.com/trannamkhanh/retailsync/blob/main/clients/demo-console/DemoConsole/Services/DemoApiClient.cs): `clients/demo-console/DemoConsole/Services/DemoApiClient.cs`

### Other components

- **POS terminal**
- **Staff and admin**

## Connections

- POS terminal → POS demo UI: operates
- POS demo UI → POS terminal client: sends events
- POS terminal client → POS event API: posts events
- POS terminal → POS event API: submits events
- Staff and admin → Middleware app: uses services
- Middleware app → POS event API: registers router (evidence: `middleware/app/main.py`)
- Middleware app → Inventory API: registers router (evidence: `middleware/app/main.py`)
- Middleware app → Product API: registers router (evidence: `middleware/app/main.py`)
- Middleware app → Job scheduler: starts scheduler (evidence: `middleware/app/main.py`)
- POS event API → Event processing: processes event (evidence: `middleware/app/api/pos.py`)
- POS event API → Database access: gets session (evidence: `middleware/app/api/pos.py`)
- POS event API → Retail data models: checks terminal
- Inventory API → Inventory service: reads inventory
- Job scheduler → Sales aggregation: runs jobs
- Job scheduler → Forecasting: runs jobs
- Job scheduler → Expiry alerts: runs jobs
- Job scheduler → HQ sync sender: runs jobs
- HQ sync sender → HQ client: sends batches
- HQ client → HQ demo API: syncs batches
- HQ demo API → Batch application: applies batch (evidence: `hq-demo/app/main.py`)
- HQ demo API → HQ database: reads batches (evidence: `hq-demo/app/main.py`)
- Batch application → HQ database: updates totals (evidence: `hq-demo/app/service.py`)
- Presenter console → Console API client: requests data
- Console API client → Middleware app: calls API
