Architecture Overview

A high-level map for anyone working on the code. (Plain-English; the README has the
exhaustive module table.)

• Backend — a FastAPI web service. The agent loop runs as a **supervised background

job** owned by a Run Manager, independent of any browser connection. All user messages
arrive by HTTP POST; a per-user WebSocket is receive-only, used to push live
updates. The database is the source of truth — answers stream into it as they're
generated, and a separate table tracks the in-flight turn so any device can recover it.

• Frontend — a single-page app in plain JavaScript modules, no heavy framework. It

renders a conversation from the database and uses the WebSocket as a live accelerant.

• Data — the main store is pluggable (local file store, Postgres, etc.; see Storage Backends). A few stores are deliberately separate and always local: the Wiki, logs, and the credentials vault.
• Resilience — runs are supervised, heartbeated, and self-healing: a watchdog revives

frozen or orphaned turns, and on restart the app resumes eligible interrupted work.

The guiding design principle is small core, drop-in everything else — see Core vs Plugins: Structure Philosophy and Extending with Drop-in Plugins.