# sachinkaushik/qsr-agent architecture

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

- Interactive diagram: https://gitdiagram.com/sachinkaushik/qsr-agent
- Repository: https://github.com/sachinkaushik/qsr-agent

## Overview

QSR Agentic Service is an edge-based restaurant assistant: operators ask questions through the web UI or Hermes CLI, Hermes uses a local OVMS/Qwen model, and MCP services own domain data and actions. A parallel event workflow receives subscribed events, gathers validated service context, proposes actions for operator approval, and reports subscribed alerts. Autonomy source is well represented; service internals and some UI wiring are unsampled, so those links are included only where documented or directly evidenced.

Main entry points: [`autonomy/worker.py`](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/worker.py) (Autonomy assembly), [`autonomy/controller.py`](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/controller.py) (Event and approval controller), [`operator-ui/app.py`](https://github.com/sachinkaushik/qsr-agent/blob/main/operator-ui/app.py) (Operator web UI), [`autonomy/event_agent.py`](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/event_agent.py) (Event reasoning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator interface"]
  node_web["Operator web UI<br/>[app.py]"]
  node_webpage["Chat and alerts<br/>[index.html]"]
end

subgraph group_agent["Hermes and model"]
  node_hermes["Hermes agent"]
  node_model["OVMS Qwen model"]
  node_skills["Domain skills"]
end

subgraph group_autonomy["Event autonomy"]
  node_worker["Autonomy assembly<br/>[worker.py]"]
  node_registry["Capability registry<br/>[registry.py]"]
  node_event_agent["Event reasoning<br/>[event_agent.py]"]
  node_capabilities["Service capabilities"]
  node_controller["Event and approval controller<br/>[controller.py]"]
  node_store[("Proposal and event state<br/>[store.py]")]
  node_mcp_client["Stdio MCP client<br/>[mcp.py]"]
  node_hermes_runner["Hermes runner<br/>[advisor.py]"]
end

subgraph group_services["Restaurant services"]
  node_kiosk["Kiosk MCP service<br/>[kiosk_server.py]"]
  node_accuracy["Order accuracy MCP service"]
  node_domain["Restaurant domain systems"]
end

node_operator(("Operator"))
node_event_source(("Subscribed event source"))

node_operator -->|"asks questions"| node_web
node_webpage -.->|"sends chat requests"| node_web
node_web -->|"runs Hermes"| node_hermes
node_operator -->|"uses CLI"| node_hermes
node_hermes -->|"queries locally"| node_model
node_hermes -->|"uses routing guidance"| node_skills
node_hermes -.->|"calls MCP tools"| node_kiosk
node_hermes -.->|"calls MCP tools"| node_accuracy
node_worker -->|"builds registry"| node_registry
node_worker -->|"registers defaults"| node_capabilities
node_worker -->|"creates clients"| node_mcp_client
node_worker -->|"creates runner"| node_hermes_runner
node_worker -->|"registers agent"| node_event_agent
node_worker -->|"creates proposal store"| node_store
node_worker -->|"builds controller"| node_controller
node_capabilities -->|"registers skill files"| node_skills
node_registry -->|"accepts event policy"| node_event_agent
node_registry -->|"constructs controller"| node_controller
node_controller -->|"records decisions"| node_store
node_controller -.->|"evaluates events"| node_event_agent
node_event_agent -.->|"requests reasoning"| node_hermes_runner
node_event_agent -->|"reads and validates tools"| node_capabilities
node_capabilities -->|"calls service tools"| node_mcp_client
node_mcp_client -->|"sends MCP requests"| node_kiosk
node_mcp_client -->|"sends MCP requests"| node_accuracy
node_controller -.->|"executes approved action"| node_mcp_client
node_event_source -->|"posts event callback"| node_web
node_web -.->|"submits event"| node_controller
node_controller -.->|"serves decisions"| node_web
node_web -.->|"streams alerts"| node_webpage
node_kiosk -->|"owns domain data"| node_domain
node_accuracy -->|"owns domain data"| node_domain

click node_web "https://github.com/sachinkaushik/qsr-agent/blob/main/operator-ui/app.py"
click node_webpage "https://github.com/sachinkaushik/qsr-agent/blob/main/operator-ui/static/index.html"
click node_skills "https://github.com/sachinkaushik/qsr-agent/tree/main/qsr-skills"
click node_worker "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/worker.py"
click node_registry "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/registry.py"
click node_event_agent "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/event_agent.py"
click node_capabilities "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/service_capabilities.py"
click node_controller "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/controller.py"
click node_store "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/store.py"
click node_mcp_client "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/mcp.py"
click node_hermes_runner "https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/advisor.py"
click node_kiosk "https://github.com/sachinkaushik/qsr-agent/blob/main/tests/mcp-services/kiosk_server.py"
click node_accuracy "https://github.com/sachinkaushik/qsr-agent/blob/main/tests/mcp-services/order_accuracy_server.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_web,node_webpage toneBlue
class node_hermes,node_model,node_skills toneAmber
class node_worker,node_registry,node_event_agent,node_capabilities,node_controller,node_store,node_mcp_client,node_hermes_runner toneMint
class node_kiosk,node_accuracy,node_domain toneRose
class node_operator,node_event_source toneIndigo
```

## Components

### Operator interface

- [Operator web UI](https://github.com/sachinkaushik/qsr-agent/blob/main/operator-ui/app.py): `operator-ui/app.py`
- [Chat and alerts](https://github.com/sachinkaushik/qsr-agent/blob/main/operator-ui/static/index.html): `operator-ui/static/index.html`

### Hermes and model

- **Hermes agent**
- **OVMS Qwen model**
- [Domain skills](https://github.com/sachinkaushik/qsr-agent/tree/main/qsr-skills): `qsr-skills`

### Event autonomy

- [Autonomy assembly](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/worker.py): `autonomy/worker.py`
- [Capability registry](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/registry.py): `autonomy/registry.py`
- [Event reasoning](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/event_agent.py): `autonomy/event_agent.py`
- [Service capabilities](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/service_capabilities.py): `autonomy/service_capabilities.py`
- [Event and approval controller](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/controller.py): `autonomy/controller.py`
- [Proposal and event state](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/store.py): `autonomy/store.py`
- [Stdio MCP client](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/mcp.py): `autonomy/mcp.py`
- [Hermes runner](https://github.com/sachinkaushik/qsr-agent/blob/main/autonomy/advisor.py): `autonomy/advisor.py`

### Restaurant services

- [Kiosk MCP service](https://github.com/sachinkaushik/qsr-agent/blob/main/tests/mcp-services/kiosk_server.py): `tests/mcp-services/kiosk_server.py`
- [Order accuracy MCP service](https://github.com/sachinkaushik/qsr-agent/blob/main/tests/mcp-services/order_accuracy_server.py): `tests/mcp-services/order_accuracy_server.py`
- **Restaurant domain systems**

### Other components

- **Operator**
- **Subscribed event source**

## Connections

- Operator → Operator web UI: asks questions (evidence: `README.md`)
- Chat and alerts → Operator web UI: sends chat requests
- Operator web UI → Hermes agent: runs Hermes (evidence: `operator-ui/app.py`)
- Operator → Hermes agent: uses CLI (evidence: `README.md`)
- Hermes agent → OVMS Qwen model: queries locally (evidence: `README.md`)
- Hermes agent → Domain skills: uses routing guidance (evidence: `README.md`)
- Hermes agent → Kiosk MCP service: calls MCP tools (evidence: `README.md`)
- Hermes agent → Order accuracy MCP service: calls MCP tools (evidence: `README.md`)
- Autonomy assembly → Capability registry: builds registry (evidence: `autonomy/worker.py`)
- Autonomy assembly → Service capabilities: registers defaults (evidence: `autonomy/worker.py`)
- Autonomy assembly → Stdio MCP client: creates clients (evidence: `autonomy/worker.py`)
- Autonomy assembly → Hermes runner: creates runner (evidence: `autonomy/worker.py`)
- Autonomy assembly → Event reasoning: registers agent (evidence: `autonomy/worker.py`)
- Autonomy assembly → Proposal and event state: creates proposal store (evidence: `autonomy/worker.py`)
- Autonomy assembly → Event and approval controller: builds controller (evidence: `autonomy/worker.py`)
- Service capabilities → Domain skills: registers skill files (evidence: `autonomy/service_capabilities.py`)
- Capability registry → Event reasoning: accepts event policy (evidence: `autonomy/registry.py`)
- Capability registry → Event and approval controller: constructs controller (evidence: `autonomy/registry.py`)
- Event and approval controller → Proposal and event state: records decisions (evidence: `autonomy/controller.py`)
- Event and approval controller → Event reasoning: evaluates events
- Event reasoning → Hermes runner: requests reasoning
- Event reasoning → Service capabilities: reads and validates tools (evidence: `autonomy/event_agent.py`)
- Service capabilities → Stdio MCP client: calls service tools
- Stdio MCP client → Kiosk MCP service: sends MCP requests
- Stdio MCP client → Order accuracy MCP service: sends MCP requests
- Event and approval controller → Stdio MCP client: executes approved action
- Subscribed event source → Operator web UI: posts event callback (evidence: `README.md`)
- Operator web UI → Event and approval controller: submits event
- Event and approval controller → Operator web UI: serves decisions
- Operator web UI → Chat and alerts: streams alerts
- Kiosk MCP service → Restaurant domain systems: owns domain data (evidence: `README.md`)
- Order accuracy MCP service → Restaurant domain systems: owns domain data (evidence: `README.md`)
