# kurtreonal/iot-dashboard architecture

> Architecture diagram of the GitHub repository kurtreonal/iot-dashboard, 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/kurtreonal/iot-dashboard
- Repository: https://github.com/kurtreonal/iot-dashboard

## Overview

Stack Moko Baby combines a player-facing QR registration, FIFO queue, physical-cabinet game and result/leaderboard flow with an operator dashboard. The React app routes users and manages API state; FastAPI owns authorization and game operations over MariaDB. The dashboard also provides analytics and Stack Intelligence, including private admin memory and review/export of sanitized routing examples. Arrows cite shown calls or README claims; undocumented subsystem wiring is omitted where source excerpts do not establish it.

Main entry points: [`backend/app/main.py`](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/main.py) (API routes), [`backend/app/assistant.py`](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant.py) (Intent and answers), [`frontend/src/App.jsx`](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/state/AppContext.jsx`](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/AppContext.jsx) (Application state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player["Player game flow"]
  node_webapp["App routing<br/>[App.jsx]"]
  node_registration["QR registration<br/>[Registration.jsx]"]
  node_ticket["Player ticket<br/>[Ticket.jsx]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
end

subgraph group_admin["Operator dashboard"]
  node_analytics["Analytics<br/>[analytics.py]"]
  node_adminui["Admin dashboard<br/>[App.jsx]"]
end

subgraph group_backend["Backend services"]
  node_appstate["Application state<br/>[AppContext.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_routes["API routes<br/>[main.py]"]
  node_security["Session security<br/>[security.py]"]
  node_database[("MariaDB persistence<br/>[database.py]")]
  node_game["Queue and results<br/>[game.py]"]
end

subgraph group_assistant["Stack Intelligence"]
  node_assistantui["Assistant interface<br/>[AdminAssistant.jsx]"]
  node_assistantctx["Assistant state"]
  node_assistantcore["Intent and answers<br/>[assistant.py]"]
  node_knowledge["Knowledge grounding"]
  node_memory[("Admin memory")]
  node_training["Training review"]
  node_interactions["Routing examples"]
end

node_players(("Players"))
node_cabinet{{"Physical cabinet"}}
node_ollama["Local Ollama"]

node_players -->|"use"| node_webapp
node_webapp -->|"routes to"| node_registration
node_webapp -->|"routes to"| node_ticket
node_webapp -->|"routes to"| node_leaderboard
node_registration -->|"registers through"| node_appstate
node_ticket -->|"reads state"| node_appstate
node_leaderboard -->|"loads rankings"| node_api
node_appstate -->|"calls"| node_api
node_api -->|"HTTP requests"| node_routes
node_routes -->|"authorizes"| node_security
node_routes -->|"queries"| node_database
node_routes -->|"delegates game actions"| node_game
node_cabinet -->|"submits results"| node_routes
node_adminui -->|"uses state"| node_appstate
node_routes -->|"collects metrics"| node_analytics
node_assistantui -->|"uses state"| node_assistantctx
node_assistantctx -->|"calls assistant endpoints"| node_api
node_routes -->|"dispatches assistant requests"| node_assistantcore
node_assistantcore -->|"reads analytics"| node_analytics
node_assistantcore -->|"uses knowledge"| node_knowledge
node_assistantcore -->|"loads and saves"| node_memory
node_assistantcore -.->|"uses local model"| node_ollama
node_assistantui -->|"reviews examples"| node_training
node_training -->|"uses routing corpus"| node_interactions
node_training -->|"stores and exports"| node_database

click node_webapp "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/App.jsx"
click node_registration "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Registration.jsx"
click node_ticket "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Ticket.jsx"
click node_leaderboard "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Leaderboard.jsx"
click node_appstate "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/AppContext.jsx"
click node_api "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/api.js"
click node_routes "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/main.py"
click node_security "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/security.py"
click node_database "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/database.py"
click node_game "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/game.py"
click node_analytics "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/analytics.py"
click node_adminui "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/App.jsx"
click node_assistantui "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/components/AdminAssistant.jsx"
click node_assistantctx "https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/AssistantContext.jsx"
click node_assistantcore "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant.py"
click node_knowledge "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_knowledge.py"
click node_memory "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_memory.py"
click node_training "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_training.py"
click node_interactions "https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_interactions.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_webapp,node_registration,node_ticket,node_leaderboard toneBlue
class node_analytics,node_adminui toneAmber
class node_appstate,node_api,node_routes,node_security,node_database,node_game toneMint
class node_assistantui,node_assistantctx,node_assistantcore,node_knowledge,node_memory,node_training,node_interactions toneRose
class node_players,node_cabinet,node_ollama toneIndigo
```

## Components

### Player game flow

- [App routing](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [QR registration](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Registration.jsx): `frontend/src/pages/Registration.jsx`
- [Player ticket](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Ticket.jsx): `frontend/src/pages/Ticket.jsx`
- [Leaderboard](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/pages/Leaderboard.jsx): `frontend/src/pages/Leaderboard.jsx`

### Operator dashboard

- [Analytics](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/analytics.py): `backend/app/analytics.py`
- [Admin dashboard](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Backend services

- [Application state](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/AppContext.jsx): `frontend/src/state/AppContext.jsx`
- [API client](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/api.js): `frontend/src/state/api.js`
- [API routes](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/main.py): `backend/app/main.py`
- [Session security](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/security.py): `backend/app/security.py`
- [MariaDB persistence](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/database.py): `backend/app/database.py`
- [Queue and results](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/game.py): `backend/app/game.py`

### Stack Intelligence

- [Assistant interface](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/components/AdminAssistant.jsx): `frontend/src/components/AdminAssistant.jsx`
- [Assistant state](https://github.com/kurtreonal/iot-dashboard/blob/main/frontend/src/state/AssistantContext.jsx): `frontend/src/state/AssistantContext.jsx`
- [Intent and answers](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant.py): `backend/app/assistant.py`
- [Knowledge grounding](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_knowledge.py): `backend/app/assistant_knowledge.py`
- [Admin memory](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_memory.py): `backend/app/assistant_memory.py`
- [Training review](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_training.py): `backend/app/assistant_training.py`
- [Routing examples](https://github.com/kurtreonal/iot-dashboard/blob/main/backend/app/assistant_interactions.py): `backend/app/assistant_interactions.py`

### Other components

- **Players**
- **Physical cabinet**
- **Local Ollama**

## Connections

- Players → App routing: use
- App routing → QR registration: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Player ticket: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Leaderboard: routes to (evidence: `frontend/src/App.jsx`)
- QR registration → Application state: registers through (evidence: `frontend/src/pages/Registration.jsx`)
- Player ticket → Application state: reads state (evidence: `frontend/src/pages/Ticket.jsx`)
- Leaderboard → API client: loads rankings (evidence: `frontend/src/pages/Leaderboard.jsx`)
- Application state → API client: calls (evidence: `frontend/src/state/AppContext.jsx`)
- API client → API routes: HTTP requests (evidence: `frontend/src/state/api.js`)
- API routes → Session security: authorizes (evidence: `backend/app/main.py`)
- API routes → MariaDB persistence: queries (evidence: `backend/app/main.py`)
- API routes → Queue and results: delegates game actions (evidence: `backend/app/main.py`)
- Physical cabinet → API routes: submits results
- Admin dashboard → Application state: uses state (evidence: `frontend/src/App.jsx`)
- API routes → Analytics: collects metrics (evidence: `backend/app/main.py`)
- Assistant interface → Assistant state: uses state (evidence: `frontend/src/components/AdminAssistant.jsx`)
- Assistant state → API client: calls assistant endpoints (evidence: `frontend/src/state/AssistantContext.jsx`)
- API routes → Intent and answers: dispatches assistant requests (evidence: `backend/app/main.py`)
- Intent and answers → Analytics: reads analytics (evidence: `backend/app/assistant.py`)
- Intent and answers → Knowledge grounding: uses knowledge (evidence: `backend/app/assistant.py`)
- Intent and answers → Admin memory: loads and saves (evidence: `backend/app/assistant.py`)
- Intent and answers → Local Ollama: uses local model
- Assistant interface → Training review: reviews examples
- Training review → Routing examples: uses routing corpus (evidence: `backend/app/assistant_training.py`)
- Training review → MariaDB persistence: stores and exports (evidence: `backend/app/assistant_training.py`)
