# itegin/it-deck architecture

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

- Interactive diagram: https://gitdiagram.com/itegin/it-deck
- Repository: https://github.com/itegin/it-deck

## Overview

IT-Deck turns a phone browser into a Windows PC control deck, with Studio on the PC for configuring tiles, decks, and access. The main runtime flow is phone interaction → backend command routing → Windows agent action → reported state back to connected clients. The README documents Studio editing, widgets, quick launch, themes, and multiple decks; these are included, though their complete backend wiring was not sampled. The launcher’s startup role is documented in its excerpt.

Main entry points: [`backend/app/main.py`](https://github.com/itegin/it-deck/blob/main/backend/app/main.py) (HTTP and WS app), [`agents/windows/agent.py`](https://github.com/itegin/it-deck/blob/main/agents/windows/agent.py) (Agent runtime), [`backend/app/ws/agent.py`](https://github.com/itegin/it-deck/blob/main/backend/app/ws/agent.py) (Agent connection handler), [`frontend/js/app.js`](https://github.com/itegin/it-deck/blob/main/frontend/js/app.js) (Deck interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["Phone deck"]
  node_deck_app["Deck interface<br/>[app.js]"]
  node_deck_render["Deck rendering<br/>[render.js]"]
  node_deck_ws["WebSocket client<br/>[ws.js]"]
  node_widgets["Live widgets<br/>[index.js]"]
end

subgraph group_backend["Backend service"]
  node_backend_app["HTTP and WS app<br/>[main.py]"]
  node_client_ws["Client command handler<br/>[client.py]"]
  node_agent_ws["Agent connection handler<br/>[agent.py]"]
  node_hub["Connection hub<br/>[hub.py]"]
  node_workspaces_api["Workspace and item APIs<br/>[workspaces.py]"]
  node_items_api["Tile APIs<br/>[items.py]"]
  node_agent_api["Agent query APIs<br/>[agents.py]"]
  node_access_api["Access settings API<br/>[access.py]"]
end

subgraph group_agent["Windows agent"]
  node_agent_runtime["Agent runtime<br/>[agent.py]"]
  node_dispatch["Command dispatch<br/>[dispatch.py]"]
  node_handlers["PC action handlers"]
  node_poller["State polling<br/>[poller.py]"]
  node_apps_helpers["App and icon queries<br/>[apps.py]"]
end

subgraph group_studio["Studio editor"]
  node_studio_ui["Studio editor<br/>[studio.js]"]
  node_studio_preview["Deck preview<br/>[studio-preview.js]"]
  node_studio_api["Studio API client<br/>[api.js]"]
end

subgraph group_state["Persistence and state"]
  node_database[("Deck database<br/>[db.py]")]
  node_models["Deck data model<br/>[models.py]"]
  node_launcher["PC launcher<br/>[launcher.py]"]
end

node_phone_user(("Phone user"))
node_weather["Weather service"]
node_agent_user(("Windows PC"))

node_phone_user -->|"uses"| node_deck_app
node_deck_app -->|"renders decks"| node_deck_render
node_deck_app -->|"sends commands"| node_deck_ws
node_deck_app -->|"mounts widgets"| node_widgets
node_widgets -.->|"fetches weather"| node_weather
node_deck_ws -->|"opens socket"| node_backend_app
node_backend_app -->|"routes client WS"| node_client_ws
node_backend_app -->|"routes agent WS"| node_agent_ws
node_client_ws -->|"loads tile"| node_models
node_client_ws -->|"dispatches command"| node_hub
node_hub -->|"forwards messages"| node_agent_ws
node_agent_ws -->|"registers agent"| node_hub
node_agent_user -->|"runs on"| node_agent_runtime
node_agent_runtime -->|"connects to"| node_backend_app
node_agent_runtime -->|"dispatches commands"| node_dispatch
node_dispatch -->|"invokes actions"| node_handlers
node_agent_runtime -->|"polls PC state"| node_poller
node_poller -->|"reports state"| node_agent_runtime
node_agent_ws -->|"broadcasts state"| node_deck_ws
node_studio_ui -->|"updates preview"| node_studio_preview
node_studio_ui -->|"requests edits"| node_studio_api
node_studio_api -->|"calls HTTP APIs"| node_backend_app
node_backend_app -->|"routes workspace requests"| node_workspaces_api
node_backend_app -->|"routes tile requests"| node_items_api
node_backend_app -->|"routes agent queries"| node_agent_api
node_backend_app -->|"routes access requests"| node_access_api
node_workspaces_api -->|"reads decks"| node_models
node_items_api -->|"writes tiles"| node_database
node_models -->|"reads deck data"| node_database
node_agent_api -->|"requests agent work"| node_hub
node_agent_api -->|"queries apps and icons"| node_apps_helpers
node_apps_helpers -->|"requests agent query"| node_agent_ws
node_launcher -->|"starts backend"| node_backend_app
node_launcher -->|"starts agent"| node_agent_runtime

click node_deck_app "https://github.com/itegin/it-deck/blob/main/frontend/js/app.js"
click node_deck_render "https://github.com/itegin/it-deck/blob/main/frontend/js/render.js"
click node_deck_ws "https://github.com/itegin/it-deck/blob/main/frontend/js/ws.js"
click node_widgets "https://github.com/itegin/it-deck/blob/main/frontend/js/widgets/index.js"
click node_backend_app "https://github.com/itegin/it-deck/blob/main/backend/app/main.py"
click node_client_ws "https://github.com/itegin/it-deck/blob/main/backend/app/ws/client.py"
click node_agent_ws "https://github.com/itegin/it-deck/blob/main/backend/app/ws/agent.py"
click node_hub "https://github.com/itegin/it-deck/blob/main/backend/app/ws/hub.py"
click node_agent_runtime "https://github.com/itegin/it-deck/blob/main/agents/windows/agent.py"
click node_dispatch "https://github.com/itegin/it-deck/blob/main/agents/windows/dispatch.py"
click node_handlers "https://github.com/itegin/it-deck/tree/main/agents/windows/handlers"
click node_poller "https://github.com/itegin/it-deck/blob/main/agents/windows/poller.py"
click node_apps_helpers "https://github.com/itegin/it-deck/blob/main/agents/windows/handlers/apps.py"
click node_studio_ui "https://github.com/itegin/it-deck/blob/main/frontend/js/studio.js"
click node_studio_preview "https://github.com/itegin/it-deck/blob/main/frontend/js/studio-preview.js"
click node_studio_api "https://github.com/itegin/it-deck/blob/main/frontend/js/api.js"
click node_workspaces_api "https://github.com/itegin/it-deck/blob/main/backend/app/api/workspaces.py"
click node_items_api "https://github.com/itegin/it-deck/blob/main/backend/app/api/items.py"
click node_agent_api "https://github.com/itegin/it-deck/blob/main/backend/app/api/agents.py"
click node_access_api "https://github.com/itegin/it-deck/blob/main/backend/app/api/access.py"
click node_database "https://github.com/itegin/it-deck/blob/main/backend/app/db.py"
click node_models "https://github.com/itegin/it-deck/blob/main/backend/app/models.py"
click node_launcher "https://github.com/itegin/it-deck/blob/main/standalone/launcher.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_deck_app,node_deck_render,node_deck_ws,node_widgets,node_phone_user toneBlue
class node_backend_app,node_client_ws,node_agent_ws,node_hub,node_workspaces_api,node_items_api,node_agent_api,node_access_api toneAmber
class node_agent_runtime,node_dispatch,node_handlers,node_poller,node_apps_helpers toneMint
class node_studio_ui,node_studio_preview,node_studio_api toneRose
class node_database,node_models,node_launcher,node_weather,node_agent_user toneIndigo
```

## Components

### Phone deck

- [Deck interface](https://github.com/itegin/it-deck/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Deck rendering](https://github.com/itegin/it-deck/blob/main/frontend/js/render.js): `frontend/js/render.js`
- [WebSocket client](https://github.com/itegin/it-deck/blob/main/frontend/js/ws.js): `frontend/js/ws.js`
- [Live widgets](https://github.com/itegin/it-deck/blob/main/frontend/js/widgets/index.js): `frontend/js/widgets/index.js`

### Backend service

- [HTTP and WS app](https://github.com/itegin/it-deck/blob/main/backend/app/main.py): `backend/app/main.py`
- [Client command handler](https://github.com/itegin/it-deck/blob/main/backend/app/ws/client.py): `backend/app/ws/client.py`
- [Agent connection handler](https://github.com/itegin/it-deck/blob/main/backend/app/ws/agent.py): `backend/app/ws/agent.py`
- [Connection hub](https://github.com/itegin/it-deck/blob/main/backend/app/ws/hub.py): `backend/app/ws/hub.py`
- [Workspace and item APIs](https://github.com/itegin/it-deck/blob/main/backend/app/api/workspaces.py): `backend/app/api/workspaces.py`
- [Tile APIs](https://github.com/itegin/it-deck/blob/main/backend/app/api/items.py): `backend/app/api/items.py`
- [Agent query APIs](https://github.com/itegin/it-deck/blob/main/backend/app/api/agents.py): `backend/app/api/agents.py`
- [Access settings API](https://github.com/itegin/it-deck/blob/main/backend/app/api/access.py): `backend/app/api/access.py`

### Windows agent

- [Agent runtime](https://github.com/itegin/it-deck/blob/main/agents/windows/agent.py): `agents/windows/agent.py`
- [Command dispatch](https://github.com/itegin/it-deck/blob/main/agents/windows/dispatch.py): `agents/windows/dispatch.py`
- [PC action handlers](https://github.com/itegin/it-deck/tree/main/agents/windows/handlers): `agents/windows/handlers`
- [State polling](https://github.com/itegin/it-deck/blob/main/agents/windows/poller.py): `agents/windows/poller.py`
- [App and icon queries](https://github.com/itegin/it-deck/blob/main/agents/windows/handlers/apps.py): `agents/windows/handlers/apps.py`

### Studio editor

- [Studio editor](https://github.com/itegin/it-deck/blob/main/frontend/js/studio.js): `frontend/js/studio.js`
- [Deck preview](https://github.com/itegin/it-deck/blob/main/frontend/js/studio-preview.js): `frontend/js/studio-preview.js`
- [Studio API client](https://github.com/itegin/it-deck/blob/main/frontend/js/api.js): `frontend/js/api.js`

### Persistence and state

- [Deck database](https://github.com/itegin/it-deck/blob/main/backend/app/db.py): `backend/app/db.py`
- [Deck data model](https://github.com/itegin/it-deck/blob/main/backend/app/models.py): `backend/app/models.py`
- [PC launcher](https://github.com/itegin/it-deck/blob/main/standalone/launcher.py): `standalone/launcher.py`

### Other components

- **Phone user**
- **Weather service**
- **Windows PC**

## Connections

- Phone user → Deck interface: uses
- Deck interface → Deck rendering: renders decks
- Deck interface → WebSocket client: sends commands
- Deck interface → Live widgets: mounts widgets
- Live widgets → Weather service: fetches weather
- WebSocket client → HTTP and WS app: opens socket
- HTTP and WS app → Client command handler: routes client WS
- HTTP and WS app → Agent connection handler: routes agent WS
- Client command handler → Deck data model: loads tile
- Client command handler → Connection hub: dispatches command
- Connection hub → Agent connection handler: forwards messages
- Agent connection handler → Connection hub: registers agent
- Windows PC → Agent runtime: runs on
- Agent runtime → HTTP and WS app: connects to
- Agent runtime → Command dispatch: dispatches commands
- Command dispatch → PC action handlers: invokes actions
- Agent runtime → State polling: polls PC state
- State polling → Agent runtime: reports state
- Agent connection handler → WebSocket client: broadcasts state
- Studio editor → Deck preview: updates preview
- Studio editor → Studio API client: requests edits
- Studio API client → HTTP and WS app: calls HTTP APIs
- HTTP and WS app → Workspace and item APIs: routes workspace requests
- HTTP and WS app → Tile APIs: routes tile requests
- HTTP and WS app → Agent query APIs: routes agent queries
- HTTP and WS app → Access settings API: routes access requests
- Workspace and item APIs → Deck data model: reads decks
- Tile APIs → Deck database: writes tiles
- Deck data model → Deck database: reads deck data
- Agent query APIs → Connection hub: requests agent work
- Agent query APIs → App and icon queries: queries apps and icons
- App and icon queries → Agent connection handler: requests agent query
- PC launcher → HTTP and WS app: starts backend
- PC launcher → Agent runtime: starts agent