# john-michaelg135/ms-pos-probe architecture

> Architecture diagram of the GitHub repository john-michaelg135/ms-pos-probe, 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/ms-pos-probe
- Repository: https://github.com/john-michaelg135/ms-pos-probe

## Overview

POS-PROBE is a sidecar for POS demand forecasting and transaction anomaly detection, with a dashboard for managers. The documented flow is legacy POS traffic through the gateway, plus read-only sales synchronization into analytics storage; the AI service exposes forecasts, analytics and alerts to the dashboard. The graph preserves these product capabilities and the separate real-time anomaly-cloning path. Some dashboard/API and proxy route wiring is documented only at the architecture level, so those edges cite the README; unsampled internals are not inferred.

Main entry points: [`gateway/Program.cs`](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Program.cs) (YARP gateway), [`ai-service/app/main.py`](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/main.py) (FastAPI app), [`ai-service/app/jobs/sync_pipeline.py`](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/sync_pipeline.py) (Sales sync pipeline), [`ai-service/app/jobs/scheduler.py`](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/scheduler.py) (Job scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Gateway integration"]
  node_gateway["YARP gateway<br/>[Program.cs]"]
  node_tagging["POS traffic tagging"]
  node_correlation["Correlation IDs"]
  node_clone["Transaction cloning"]
  node_queue["Clone channel"]
  node_forwarder["Anomaly forwarder"]
end

subgraph group_ai["AI service"]
  node_api["FastAPI app<br/>[main.py]"]
  node_sync["Sales sync pipeline<br/>[sync_pipeline.py]"]
  node_scheduler["Job scheduler<br/>[scheduler.py]"]
  node_forecast["Demand forecasting<br/>[forecast_engine.py]"]
  node_anomaly["Anomaly detection<br/>[anomaly_engine.py]"]
  node_analytics["Analytics endpoints<br/>[analytics.py]"]
  node_forecast_api["Forecast endpoints<br/>[forecast.py]"]
  node_anomaly_api["Anomaly endpoints<br/>[anomaly.py]"]
  node_alerts["Alert history and push<br/>[alerts.py]"]
  node_metrics["Service metrics<br/>[metrics.py]"]
  node_auth["JWT verification<br/>[auth.py]"]
end

subgraph group_data["Analytics data"]
  node_db_access["Database connections<br/>[database.py]"]
  node_schema["DuckDB schema<br/>[database.py]"]
  node_duckdb[("DuckDB analytics store")]
  node_redis[("Redis cache and watermark")]
end

subgraph group_dashboard["Manager dashboard"]
  node_dashboard["Manager dashboard<br/>[page.tsx]"]
  node_forecast_ui["Forecast and quota views<br/>[page.tsx]"]
  node_alerts_ui["Alert review<br/>[page.tsx]"]
  node_analytics_ui["Analytics and reports<br/>[page.tsx]"]
  node_accuracy_ui["Forecast accuracy<br/>[page.tsx]"]
  node_auth_ui["Dashboard authentication<br/>[page.tsx]"]
end

node_pos(("POS / Ecommerce"))
node_legacy["Legacy gateway"]
node_postgres[("Legacy PostgreSQL")]

node_pos -->|"sends traffic"| node_gateway
node_gateway -->|"proxies legacy requests"| node_legacy
node_gateway -->|"routes probe API"| node_api
node_gateway -->|"registers middleware"| node_correlation
node_gateway -->|"registers middleware"| node_tagging
node_gateway -->|"registers middleware"| node_clone
node_clone -->|"enqueues clones"| node_queue
node_gateway -->|"registers channel"| node_queue
node_gateway -->|"starts service"| node_forwarder
node_forwarder -->|"reads payloads"| node_queue
node_forwarder -->|"posts anomaly data"| node_api
node_api -->|"registers sync routes"| node_sync
node_api -->|"registers routes"| node_analytics
node_api -->|"registers routes"| node_forecast_api
node_api -->|"registers routes"| node_anomaly_api
node_api -->|"registers routes"| node_alerts
node_api -->|"registers routes"| node_metrics
node_api -->|"initializes schema"| node_schema
node_api -->|"starts scheduler"| node_scheduler
node_scheduler -->|"schedules pipeline"| node_sync
node_scheduler -->|"runs forecasting"| node_forecast
node_scheduler -->|"runs detection"| node_anomaly
node_sync -->|"reads sales"| node_postgres
node_sync -->|"writes transactions"| node_duckdb
node_sync -->|"reads and writes watermark"| node_redis
node_sync -->|"invokes forecasting"| node_forecast
node_sync -->|"invokes detection"| node_anomaly
node_sync -->|"broadcasts new alerts"| node_alerts
node_forecast_api -->|"requests forecasts"| node_forecast
node_anomaly_api -->|"requests detection"| node_anomaly
node_analytics -->|"queries analytics"| node_db_access
node_alerts -->|"queries alert data"| node_db_access
node_db_access -->|"connects to"| node_duckdb
node_schema -->|"creates tables"| node_duckdb
node_forecast_api -->|"verifies access"| node_auth
node_analytics -->|"verifies access"| node_auth
node_alerts -->|"verifies access"| node_auth
node_dashboard -->|"uses probe services"| node_gateway
node_forecast_ui -->|"requests forecasts"| node_gateway
node_alerts_ui -->|"retrieves alerts"| node_gateway
node_analytics_ui -->|"requests analytics"| node_gateway
node_accuracy_ui -->|"requests accuracy data"| node_gateway
node_auth_ui -.->|"authenticates dashboard"| node_gateway

click node_gateway "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Program.cs"
click node_tagging "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/PosTrafficTaggingMiddleware.cs"
click node_correlation "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/CorrelationIdMiddleware.cs"
click node_clone "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/TransactionCloningMiddleware.cs"
click node_queue "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Services/AnomalyCloneChannel.cs"
click node_forwarder "https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Services/AnomalyForwarderService.cs"
click node_api "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/main.py"
click node_sync "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/sync_pipeline.py"
click node_scheduler "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/scheduler.py"
click node_forecast "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/forecast_engine.py"
click node_anomaly "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/anomaly_engine.py"
click node_analytics "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/analytics.py"
click node_forecast_api "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/forecast.py"
click node_anomaly_api "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/anomaly.py"
click node_alerts "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/alerts.py"
click node_metrics "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/metrics.py"
click node_auth "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/auth.py"
click node_db_access "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/database.py"
click node_schema "https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/schemas/database.py"
click node_dashboard "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/page.tsx"
click node_forecast_ui "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/forecast/page.tsx"
click node_alerts_ui "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/alerts/page.tsx"
click node_analytics_ui "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/analytics/page.tsx"
click node_accuracy_ui "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/accuracy/page.tsx"
click node_auth_ui "https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/signin/page.tsx"

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_gateway,node_tagging,node_correlation,node_clone,node_queue,node_forwarder toneBlue
class node_api,node_sync,node_scheduler,node_forecast,node_anomaly,node_analytics,node_forecast_api,node_anomaly_api,node_alerts,node_metrics,node_auth,node_postgres toneAmber
class node_db_access,node_schema,node_duckdb,node_redis toneMint
class node_dashboard,node_forecast_ui,node_alerts_ui,node_analytics_ui,node_accuracy_ui,node_auth_ui toneRose
class node_pos,node_legacy toneIndigo
```

## Components

### Gateway integration

- [YARP gateway](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Program.cs): `gateway/Program.cs`
- [POS traffic tagging](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/PosTrafficTaggingMiddleware.cs): `gateway/Middlewares/PosTrafficTaggingMiddleware.cs`
- [Correlation IDs](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/CorrelationIdMiddleware.cs): `gateway/Middlewares/CorrelationIdMiddleware.cs`
- [Transaction cloning](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Middlewares/TransactionCloningMiddleware.cs): `gateway/Middlewares/TransactionCloningMiddleware.cs`
- [Clone channel](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Services/AnomalyCloneChannel.cs): `gateway/Services/AnomalyCloneChannel.cs`
- [Anomaly forwarder](https://github.com/john-michaelg135/ms-pos-probe/blob/main/gateway/Services/AnomalyForwarderService.cs): `gateway/Services/AnomalyForwarderService.cs`

### AI service

- [FastAPI app](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Sales sync pipeline](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/sync_pipeline.py): `ai-service/app/jobs/sync_pipeline.py`
- [Job scheduler](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/jobs/scheduler.py): `ai-service/app/jobs/scheduler.py`
- [Demand forecasting](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/forecast_engine.py): `ai-service/app/services/forecast_engine.py`
- [Anomaly detection](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/anomaly_engine.py): `ai-service/app/services/anomaly_engine.py`
- [Analytics endpoints](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/analytics.py): `ai-service/app/routers/analytics.py`
- [Forecast endpoints](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/forecast.py): `ai-service/app/routers/forecast.py`
- [Anomaly endpoints](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/anomaly.py): `ai-service/app/routers/anomaly.py`
- [Alert history and push](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/alerts.py): `ai-service/app/routers/alerts.py`
- [Service metrics](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/routers/metrics.py): `ai-service/app/routers/metrics.py`
- [JWT verification](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/auth.py): `ai-service/app/services/auth.py`

### Analytics data

- [Database connections](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/services/database.py): `ai-service/app/services/database.py`
- [DuckDB schema](https://github.com/john-michaelg135/ms-pos-probe/blob/main/ai-service/app/schemas/database.py): `ai-service/app/schemas/database.py`
- **DuckDB analytics store**
- **Redis cache and watermark**

### Manager dashboard

- [Manager dashboard](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/page.tsx): `dashboard/src/app/page.tsx`
- [Forecast and quota views](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/forecast/page.tsx): `dashboard/src/app/forecast/page.tsx`
- [Alert review](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/alerts/page.tsx): `dashboard/src/app/alerts/page.tsx`
- [Analytics and reports](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/analytics/page.tsx): `dashboard/src/app/analytics/page.tsx`
- [Forecast accuracy](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/accuracy/page.tsx): `dashboard/src/app/accuracy/page.tsx`
- [Dashboard authentication](https://github.com/john-michaelg135/ms-pos-probe/blob/main/dashboard/src/app/signin/page.tsx): `dashboard/src/app/signin/page.tsx`

### Other components

- **POS / Ecommerce**
- **Legacy gateway**
- **Legacy PostgreSQL**

## Connections

- POS / Ecommerce → YARP gateway: sends traffic
- YARP gateway → Legacy gateway: proxies legacy requests
- YARP gateway → FastAPI app: routes probe API
- YARP gateway → Correlation IDs: registers middleware (evidence: `gateway/Program.cs`)
- YARP gateway → POS traffic tagging: registers middleware (evidence: `gateway/Program.cs`)
- YARP gateway → Transaction cloning: registers middleware (evidence: `gateway/Program.cs`)
- Transaction cloning → Clone channel: enqueues clones (evidence: `gateway/Middlewares/TransactionCloningMiddleware.cs`)
- YARP gateway → Clone channel: registers channel (evidence: `gateway/Program.cs`)
- YARP gateway → Anomaly forwarder: starts service (evidence: `gateway/Program.cs`)
- Anomaly forwarder → Clone channel: reads payloads (evidence: `gateway/Services/AnomalyForwarderService.cs`)
- Anomaly forwarder → FastAPI app: posts anomaly data (evidence: `gateway/Services/AnomalyForwarderService.cs`)
- FastAPI app → Sales sync pipeline: registers sync routes (evidence: `ai-service/app/main.py`)
- FastAPI app → Analytics endpoints: registers routes (evidence: `ai-service/app/main.py`)
- FastAPI app → Forecast endpoints: registers routes (evidence: `ai-service/app/main.py`)
- FastAPI app → Anomaly endpoints: registers routes (evidence: `ai-service/app/main.py`)
- FastAPI app → Alert history and push: registers routes (evidence: `ai-service/app/main.py`)
- FastAPI app → Service metrics: registers routes (evidence: `ai-service/app/main.py`)
- FastAPI app → DuckDB schema: initializes schema (evidence: `ai-service/app/main.py`)
- FastAPI app → Job scheduler: starts scheduler (evidence: `ai-service/app/main.py`)
- Job scheduler → Sales sync pipeline: schedules pipeline (evidence: `ai-service/app/jobs/scheduler.py`)
- Job scheduler → Demand forecasting: runs forecasting (evidence: `ai-service/app/jobs/scheduler.py`)
- Job scheduler → Anomaly detection: runs detection (evidence: `ai-service/app/jobs/scheduler.py`)
- Sales sync pipeline → Legacy PostgreSQL: reads sales (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Sales sync pipeline → DuckDB analytics store: writes transactions (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Sales sync pipeline → Redis cache and watermark: reads and writes watermark (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Sales sync pipeline → Demand forecasting: invokes forecasting (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Sales sync pipeline → Anomaly detection: invokes detection (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Sales sync pipeline → Alert history and push: broadcasts new alerts (evidence: `ai-service/app/jobs/sync_pipeline.py`)
- Forecast endpoints → Demand forecasting: requests forecasts (evidence: `ai-service/app/routers/forecast.py`)
- Anomaly endpoints → Anomaly detection: requests detection (evidence: `ai-service/app/routers/anomaly.py`)
- Analytics endpoints → Database connections: queries analytics (evidence: `ai-service/app/routers/analytics.py`)
- Alert history and push → Database connections: queries alert data (evidence: `ai-service/app/routers/alerts.py`)
- Database connections → DuckDB analytics store: connects to (evidence: `ai-service/app/services/database.py`)
- DuckDB schema → DuckDB analytics store: creates tables (evidence: `ai-service/app/schemas/database.py`)
- Forecast endpoints → JWT verification: verifies access (evidence: `ai-service/app/routers/forecast.py`)
- Analytics endpoints → JWT verification: verifies access (evidence: `ai-service/app/routers/analytics.py`)
- Alert history and push → JWT verification: verifies access (evidence: `ai-service/app/routers/alerts.py`)
- Manager dashboard → YARP gateway: uses probe services
- Forecast and quota views → YARP gateway: requests forecasts
- Alert review → YARP gateway: retrieves alerts
- Analytics and reports → YARP gateway: requests analytics
- Forecast accuracy → YARP gateway: requests accuracy data
- Dashboard authentication → YARP gateway: authenticates dashboard
