Architecture
Cadet Cloud has three main domains that work together: a runtime that manages conversations and tools, a native client for macOS, and a gateway that handles all external communication.
Cloud Domains
Assistant Runtime
assistant/
Bun + TypeScript runtime that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes a Unix domain socket for the native client, plus an HTTP API consumed by the gateway.
Native Clients
clients/
Native macOS app built with Swift via CadetAssistantShared. A menu bar assistant with computer-use (accessibility + CGEvent), chat, and full tool access.
Gateway
gateway/
Standalone Bun + TypeScript service that serves as the public ingress boundary for all external webhooks and callbacks. Owns Telegram integration end-to-end (receives webhooks, routes to assistants, delivers replies). Routes Twilio voice webhooks, handles OAuth callbacks, and optionally acts as an authenticated reverse proxy for the assistant runtime API.
Repository Structure
/ ├── .github/ # GitHub Actions workflows ├── assets/ # Brand assets and images ├── assistant/ # Bun-based assistant runtime (runtime, CLI, HTTP API) ├── cli/ # Cadet CLI ├── clients/ # Native clients (macOS, iOS, Windows, web, docs, Chrome extension) ├── credential-executor/ # Credential Execution Service (isolated RPC boundary) ├── docs/ # Internal engineering docs and proposals ├── gateway/ # Gateway service (Telegram, Twilio, OAuth, reverse proxy) ├── meta/ # Meta configuration ├── packages/ # Shared private packages (CES contracts, credential storage, egress proxy) ├── plugins/ # Plugin workspace (MCP catalog, marketplace) ├── scripts/ # Utility scripts (publishing, tunneling, releases) └── skills/ # Bundled skill definitions
Architecture Docs
Detailed architecture docs are split by ownership domain, close to the code:
| Document | What's Covered |
|---|---|
| Architecture | Cross-system index — invariants, domain boundaries, data flow |
| Assistant Architecture | Runtime internals — conversation loop, tool dispatch, memory, scheduling |
| Gateway Architecture | Ingress boundary — webhooks, Telegram, Twilio, reverse proxy |
| Security Architecture | Security model — sandbox, credentials, permissions, secret handling |
| Memory Architecture | Memory system — extraction, recall, provenance gates |
| Scheduling Architecture | Heartbeats, wake intents, and task queues |
| Integrations Architecture | How OAuth2 skills, channels, and plugins attach to the assistant |
| Turn Actor Architecture | How a conversation turn is routed and executed |
| Credential Execution Service | CES — credential isolation, secure commands, RPC boundary |