# khoadinhnguyen/restaurantos architecture

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

- Interactive diagram: https://gitdiagram.com/khoadinhnguyen/restaurantos
- Repository: https://github.com/khoadinhnguyen/restaurantos

## Overview

RestaurantOS is a distributed restaurant-chain ordering system. A client request enters the gateway, which routes it to a region; the region processes orders against its own stock and database. If a region is unreachable, the gateway can park the order for later delivery. Region events reach HQ asynchronously for reporting. The simulation prepares and replays order data, injects failures, and checks outcomes. The README documents failover and cross-region queries, but the supplied tree has no coordinator module; those capabilities are shown at the documented level. Some service wiring is unsampled, so edges are limited to shown code or README statements.

Main entry points: [`src/restaurantos/gateway/app.py`](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/app.py) (Gateway API), [`src/restaurantos/region/orders.py`](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/orders.py) (Order Transactions), [`src/restaurantos/relay/worker.py`](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/worker.py) (Relay Worker), [`src/restaurantos/sim/bootstrap.py`](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/bootstrap.py) (Cluster Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Gateway and Routing"]
  node_gateway["Gateway API<br/>[app.py]"]
  node_directory["Region Directory<br/>[directory.py]"]
  node_gateway_orders["Order Routing<br/>[orders.py]"]
  node_catalog["Menu and Vendors<br/>[menu_publish.py]"]
end

subgraph group_regional["Regional Operations"]
  node_region_orders["Order Transactions<br/>[orders.py]"]
  node_region_status["Order Status<br/>[status.py]"]
  node_region_menu["Regional Menu<br/>[menu.py]"]
  node_region_stock["Regional Stock<br/>[stock.py]"]
  node_region_db[("Region Database")]
  node_standby[("Live Standby")]
end

subgraph group_hq["HQ and Replication"]
  node_holding["Holding Queue<br/>[holding.py]"]
  node_hq_db[("HQ Database")]
  node_relay_worker["Relay Worker<br/>[worker.py]"]
  node_outbox["Region Outbox<br/>[outbox.py]"]
  node_hq_apply["HQ Event Apply<br/>[hq_apply.py]"]
  node_hq_queries["Cross-Region Queries<br/>[summary.py]"]
end

subgraph group_simulation["Simulation and Validation"]
  node_sim_bootstrap["Cluster Bootstrap<br/>[bootstrap.py]"]
  node_data_load["Dataset Loading<br/>[loading.py]"]
  node_replay_data["Replay Data Cache<br/>[replaydata.py]"]
  node_playback["Order Playback<br/>[playback.py]"]
  node_faults["Fault Injection<br/>[toxiproxy.py]"]
  node_data_check["Outcome Checks<br/>[datacheck.py]"]
end

subgraph group_runtime["Shared Runtime"]
  node_failover["Primary Failover"]
  node_shared_db["DB Connectivity<br/>[db.py]"]
  node_cluster_model["Cluster Model<br/>[cluster.py]"]
  node_contracts["Shared Contracts<br/>[models.py]"]
end

node_client(("Order Client"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes vendors"| node_directory
node_gateway -->|"handles orders"| node_gateway_orders
node_gateway_orders -->|"places order"| node_region_orders
node_gateway_orders -->|"parks unreachable"| node_holding
node_region_orders -->|"commits order"| node_region_db
node_region_status -->|"reads status"| node_region_db
node_region_menu -->|"serves menu"| node_region_db
node_region_stock -->|"updates stock"| node_region_db
node_region_db -->|"streams replication"| node_standby
node_failover -->|"promotes standby"| node_standby
node_failover -->|"advances epoch"| node_region_db
node_region_orders -->|"writes event"| node_outbox
node_relay_worker -->|"reads pending"| node_outbox
node_relay_worker -->|"applies batch"| node_hq_apply
node_hq_apply -->|"writes events"| node_hq_db
node_gateway -->|"serves summaries"| node_hq_queries
node_hq_queries -->|"queries regions"| node_hq_db
node_gateway -->|"publishes menu"| node_catalog
node_sim_bootstrap -->|"loads dataset"| node_data_load
node_data_load -->|"builds cache"| node_replay_data
node_playback -->|"streams orders"| node_replay_data
node_playback -->|"posts orders"| node_gateway
node_sim_bootstrap -->|"configures faults"| node_faults
node_data_check -->|"checks loaded data"| node_data_load
node_sim_bootstrap -->|"validates setup"| node_data_check
node_gateway -->|"uses pools"| node_shared_db
node_relay_worker -->|"opens pools"| node_shared_db
node_shared_db -->|"builds connection info"| node_cluster_model
node_region_orders -->|"uses order models"| node_contracts

click node_gateway "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/app.py"
click node_directory "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/directory.py"
click node_gateway_orders "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/orders.py"
click node_holding "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/holding.py"
click node_region_orders "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/orders.py"
click node_region_status "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/status.py"
click node_region_menu "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/menu.py"
click node_region_stock "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/stock.py"
click node_relay_worker "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/worker.py"
click node_outbox "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/outbox.py"
click node_hq_apply "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/hq_apply.py"
click node_hq_queries "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/summary.py"
click node_catalog "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/menu_publish.py"
click node_sim_bootstrap "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/bootstrap.py"
click node_data_load "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/loading.py"
click node_replay_data "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/replaydata.py"
click node_playback "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/playback.py"
click node_faults "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/toxiproxy.py"
click node_data_check "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/datacheck.py"
click node_shared_db "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/db.py"
click node_cluster_model "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/cluster.py"
click node_contracts "https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/models.py"

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_directory,node_gateway_orders,node_catalog,node_client toneBlue
class node_region_orders,node_region_status,node_region_menu,node_region_stock,node_region_db,node_standby toneAmber
class node_holding,node_hq_db,node_relay_worker,node_outbox,node_hq_apply,node_hq_queries toneMint
class node_sim_bootstrap,node_data_load,node_replay_data,node_playback,node_faults,node_data_check toneRose
class node_failover,node_shared_db,node_cluster_model,node_contracts toneIndigo
```

## Components

### Gateway and Routing

- [Gateway API](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/app.py): `src/restaurantos/gateway/app.py`
- [Region Directory](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/directory.py): `src/restaurantos/gateway/directory.py`
- [Order Routing](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/orders.py): `src/restaurantos/gateway/orders.py`
- [Menu and Vendors](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/menu_publish.py): `src/restaurantos/gateway/menu_publish.py`

### Regional Operations

- [Order Transactions](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/orders.py): `src/restaurantos/region/orders.py`
- [Order Status](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/status.py): `src/restaurantos/region/status.py`
- [Regional Menu](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/menu.py): `src/restaurantos/region/menu.py`
- [Regional Stock](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/region/stock.py): `src/restaurantos/region/stock.py`
- **Region Database**
- **Live Standby**

### HQ and Replication

- [Holding Queue](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/holding.py): `src/restaurantos/relay/holding.py`
- **HQ Database**
- [Relay Worker](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/worker.py): `src/restaurantos/relay/worker.py`
- [Region Outbox](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/outbox.py): `src/restaurantos/relay/outbox.py`
- [HQ Event Apply](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/relay/hq_apply.py): `src/restaurantos/relay/hq_apply.py`
- [Cross-Region Queries](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/gateway/summary.py): `src/restaurantos/gateway/summary.py`

### Simulation and Validation

- [Cluster Bootstrap](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/bootstrap.py): `src/restaurantos/sim/bootstrap.py`
- [Dataset Loading](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/loading.py): `src/restaurantos/sim/loading.py`
- [Replay Data Cache](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/replaydata.py): `src/restaurantos/sim/replaydata.py`
- [Order Playback](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/playback.py): `src/restaurantos/sim/playback.py`
- [Fault Injection](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/toxiproxy.py): `src/restaurantos/sim/toxiproxy.py`
- [Outcome Checks](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/sim/datacheck.py): `src/restaurantos/sim/datacheck.py`

### Shared Runtime

- **Primary Failover**
- [DB Connectivity](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/db.py): `src/restaurantos/common/db.py`
- [Cluster Model](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/cluster.py): `src/restaurantos/common/cluster.py`
- [Shared Contracts](https://github.com/khoadinhnguyen/restaurantos/blob/main/src/restaurantos/common/models.py): `src/restaurantos/common/models.py`

### Other components

- **Order Client**

## Connections

- Order Client → Gateway API: sends requests
- Gateway API → Region Directory: routes vendors (evidence: `src/restaurantos/gateway/app.py`)
- Gateway API → Order Routing: handles orders (evidence: `src/restaurantos/gateway/app.py`)
- Order Routing → Order Transactions: places order (evidence: `src/restaurantos/gateway/orders.py`)
- Order Routing → Holding Queue: parks unreachable
- Order Transactions → Region Database: commits order (evidence: `src/restaurantos/region/orders.py`)
- Order Status → Region Database: reads status
- Regional Menu → Region Database: serves menu
- Regional Stock → Region Database: updates stock
- Region Database → Live Standby: streams replication
- Primary Failover → Live Standby: promotes standby
- Primary Failover → Region Database: advances epoch
- Order Transactions → Region Outbox: writes event (evidence: `src/restaurantos/region/orders.py`)
- Relay Worker → Region Outbox: reads pending (evidence: `src/restaurantos/relay/worker.py`)
- Relay Worker → HQ Event Apply: applies batch (evidence: `src/restaurantos/relay/worker.py`)
- HQ Event Apply → HQ Database: writes events
- Gateway API → Cross-Region Queries: serves summaries (evidence: `src/restaurantos/gateway/app.py`)
- Cross-Region Queries → HQ Database: queries regions
- Gateway API → Menu and Vendors: publishes menu (evidence: `src/restaurantos/gateway/app.py`)
- Cluster Bootstrap → Dataset Loading: loads dataset (evidence: `src/restaurantos/sim/bootstrap.py`)
- Dataset Loading → Replay Data Cache: builds cache (evidence: `src/restaurantos/sim/replaydata.py`)
- Order Playback → Replay Data Cache: streams orders (evidence: `src/restaurantos/sim/playback.py`)
- Order Playback → Gateway API: posts orders (evidence: `src/restaurantos/sim/playback.py`)
- Cluster Bootstrap → Fault Injection: configures faults (evidence: `src/restaurantos/sim/bootstrap.py`)
- Outcome Checks → Dataset Loading: checks loaded data (evidence: `src/restaurantos/sim/datacheck.py`)
- Cluster Bootstrap → Outcome Checks: validates setup (evidence: `src/restaurantos/sim/bootstrap.py`)
- Gateway API → DB Connectivity: uses pools (evidence: `src/restaurantos/gateway/app.py`)
- Relay Worker → DB Connectivity: opens pools (evidence: `src/restaurantos/relay/worker.py`)
- DB Connectivity → Cluster Model: builds connection info (evidence: `src/restaurantos/common/db.py`)
- Order Transactions → Shared Contracts: uses order models (evidence: `src/restaurantos/region/orders.py`)
