Architecture

OpenBox is a Python server bound to loopback, with a browser interface. A native host starts the server and shows its interface in a window. Without a native host, OpenBox opens the same interface in a browser app window.

Request path

flowchart LR
    accTitle: OpenBox architecture
    accDescr: A native window or a browser window talks to web_app.py. The server reads and writes library state, and it calls plugins and launch code.
    nativeWin["Native window<br/>WebKitGTK, WebView2, or WKWebView"]
    browserWin["Browser app window<br/>openbox --web"]
    webapp["web_app.py<br/>loopback server and REST API"]
    stateStore["state_store.py<br/>library.json with atomic writes"]
    readModel["SQLite read model<br/>optional, JSON stays canonical"]
    pluginRun["plugin_runner.py<br/>sandboxed plugin processes"]
    launcher["openbox.py and emulators.py<br/>launch and emulator profiles"]
    nativeWin -->|starts| webapp
    browserWin -->|loopback HTTP| webapp
    webapp --> stateStore
    webapp --> readModel
    webapp --> pluginRun
    webapp --> launcher

Loading

Key modules

Module	Role
web_app.py	Loopback server and REST API, the shared core
routes.py	GET and POST route tables: the frozen v1 surface and additive v2 routes
handlers/	Route handlers, one module per domain
state_store.py	Schema-versioned state with atomic writes and snapshots
webapp_state.py	Event bus facade over the state owner
pkg/state/	State, caches, launch, and operations
pkg/platform_compat.py	The platform seam: locking, processes, quoting, and paths
pkg/parity/	Parity modules for the LaunchBox capability matrix
importers.py	Steam, Heroic, Lutris, and ROM imports
emulators.py	Emulator profiles and Flathub management
plugin_runner.py	Sandboxed plugin subprocess runner
static/	Frontend JavaScript modules, the search worker, and app.css
themes/	Stock theme CSS, which overrides :root tokens only
emulator_defs/	YAML emulator definitions
native_host.c, native_host_win.c, native_host_mac.m	Native window hosts for Linux, Windows, and macOS

Constraints that shape the code

• The runtime uses only the Python standard library. scripts/check_dependencies.py enforces it.
• The v1 HTTP surface is frozen. scripts/check_v1_contract.py fails the gate on drift.
• Feature surfaces only grow. Removing one moves its entry to a retired ledger with a reason (ADR 0060).
• Colors, spacing, and type come from static/app.css :root tokens. scripts/check_tokens.py enforces it.
• Platform differences stay behind pkg/platform_compat.py (ADR 0048).

Decision records

ADR	Decision
0001	Native host: a WebKitGTK C shim that renders the loopback UI
0002	Repository layout, AGENTS.md, and CI gates
0008	Splitting webapp_state.py into focused state modules
0012	Emulator registry schema and ambiguity policy
0013	Artifact-first release gates and support matrix
0014	SQLite read model
0048	Windows support
0050	Plugin API v1 freeze and catalog trust model
0056	Plugin trust model
0060	Feature-regression ratchets
0085	macOS support
0086	Platform capability contract

Gates

Command	What it runs
make check	The full gate, on Linux
make ratchets	The feature-regression ratchets alone
make contracts	Regenerates the frozen baselines after an intentional surface change

The design system is documented in DESIGN.md.

See also: Contributing.