Architecture

Standalone mode

Since v0.3.0 the main mode is standalone: a single ITDeck.exe (PyInstaller onefile) starts itself with --role backend and --role agent, giving two separate processes right on the controlled PC.

The launcher watches them and restarts a crashed agent. Its window opens with what is happening now: the QR code for the phone, open decks, the Windows agent and the camera; rare actions are tucked into “Settings”.

Processes and PC shutdown

Both processes sit in a Windows job object: however the launcher ends (“Exit”, Windows shutdown or “End task” in Task Manager), the kernel stops them together with it, and IT-Deck does not delay a PC shutdown.

Anything started from the tiles keeps running. A second copy does not start and explains that the port is already taken.

Gentle on games

While no phone has opened the deck, the agent does not poll sound and processes; the backend and the agent's worker thread run at a lowered priority, while programs started from tiles run at the normal one.

The measured cost with a phone open is about 0.1 ms of work per second. The webcam follows the same rule: while it is off, its part is not running at all.

Where the data lives

Tiles, decks, tokens and the port live in %LOCALAPPDATA%\IT-Deck, not in the exe, so they survive an update.

Three parts

Inside are the same three parts, connected by persistent WebSocket connections:

• Backend (FastAPI + SQLite): serves the REST snapshot, the frontend's static files and both WebSocket routes. In the former server variant it is a Docker container on a separate machine
• Windows agent: a persistent connection to the backend, runs commands, polls local state (for example microphone mute) on a timer
• Frontend: a vanilla JS/CSS PWA with no build step, talking to the backend over its own WebSocket

Backend

FastAPI + SQLite · exe or Docker

A FastAPI backend with SQLite. It serves the REST state snapshot, hands out the frontend's static files and handles both WebSocket routes, to the Windows agent and to the phone. The main mode is a separate process inside ITDeck.exe right on the controlled PC; the former variant is a Docker container on a separate server.

Windows agent

Python · persistent connection

Holds a persistent connection to the backend and runs the commands that arrive. Local state, such as whether the microphone is muted, is polled on a timer and sent back.

PWA dashboard

vanilla JS · no build step

A frontend with no build step: plain JS and CSS served straight from disk. It talks to the backend over its own WebSocket: tap a tile and the command is on its way.

The webcam from the inside

• The phone sends video over WebRTC to itdeck-cam.exe (C++), which decodes it on the GPU; it runs only while streaming
• Frames go to IT-Deck's own virtual camera on Windows 11, so video apps see it as an ordinary one
• The phone gives its camera only to a secure page, so IT-Deck has its own HTTPS with a local certificate for it