Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs: architecture & design overview (CHOO-1251) (#49)
Louis Amaudruz67cd68a01a58
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdnew file mode 100644index 000000000..fcd671e7b--- /dev/null+++ b/docs/ARCHITECTURE.md@@ -0,0 +1,347 @@+# Switch — Architecture & Design++This document describes how Switch is built: its components, how they fit+together, and what each part is responsible for. It is meant as a map — a+reviewer or new contributor should be able to read it and know **where in the+code** to go to verify how something works.++Paths below are relative to the repository root. The backend package lives under+`core/switch_core/` (import root `switch_core`).++---++## 1. Overview++Switch is an AI-agent orchestration and governance platform. It lets third-party+AI agents and humans collaborate in shared **rooms**, using a Matrix homeserver+([Tuwunel](https://github.com/matrix-construct/tuwunel), a conduwuit fork) as the+internal message bus. Agents connect through an **Agent Bridge** (an HTTP API and+an MCP server); humans participate from the chat tools they already use+(Slack, Mattermost, Discord, Teams) through **collaboration bridges** that relay+messages both ways. Operators manage the platform through a **gateway** API and+its dashboard.++Everything that happens in a room is a Matrix event. Each participant — every+agent, every bridged human, and a few system actors — is represented by a Matrix+client connected to the homeserver. Switch's job is to translate between those+Matrix events and the agent-facing API/MCP surface, to provision and govern the+rooms, and to bridge them out to external platforms.++---++## 2. High-level architecture++The backend is a single FastAPI service, assembled in+[`core/switch_core/main.py`](../core/switch_core/main.py). The Agent Bridge app is+the root ASGI app; the MCP server, health check, collaboration bridge, and+gateway are mounted onto it:++- `POST/GET /agents/...` — Agent Bridge HTTP API+- `/mcp` — MCP server (agent tool surface)+- `/health` — health check+- `/collab` — collaboration bridge admin API (bridge CRUD/onboarding)+- `/gateway` — gateway management API (backs the operator dashboard)++```mermaid+flowchart LR+ subgraph ext["External chat platforms"]+ SL[Slack]+ MM[Mattermost]+ DC[Discord]+ TE[Teams]+ end++ subgraph agents["AI agents (connect via MCP or HTTP)"]+ A1[Claude Code<br/>MCP]+ A2[Other agents<br/>HTTP API]+ end++ subgraph svc["Switch service (FastAPI — switch_core.main)"]+ AB[Agent Bridge<br/>/agents + /mcp]+ CB[Collaboration Bridge<br/>adapters + puppets]+ GW[Gateway API<br/>/gateway]+ CORE[Room service + Matrix clients]+ end++ MX[("Matrix / Tuwunel")]+ DB[("PostgreSQL")]+ OPS[Operator dashboard SPA]++ A1 <-->|MCP / long-poll| AB+ A2 <-->|HTTP / long-poll| AB+ SL <-->|WebSocket| CB+ MM <-->|WebSocket| CB+ DC <-->|WebSocket| CB+ TE <-->|HTTP push| CB+ AB --> CORE+ CB --> CORE+ CORE <-->|matrix-nio| MX+ svc --> DB+ OPS -->|/gateway| GW+```++### Components++| Component | Where | Responsibility |+|-----------|-------|----------------|+| Agent Bridge | `bridges/agent/` | Server-side entry point for agents: HTTP API + MCP server, event delivery, task protocol, mediation, moderation. |+| Collaboration bridges | `bridges/collaboration/` | Two-way relay between external chat platforms and Matrix rooms, via per-platform adapters and puppet clients. |+| Resource bridge | `bridges/resource/` | Handles resource + mediation requests (tool/model access, room-document load/CRUD) via the resource-manager client. |+| Matrix clients | `clients/` | One `matrix-nio` client per participant (agent, bridge, user) and per system actor (admin, resource manager). |+| Room service | `room_service.py`, `rooms_yaml.py` | Room provisioning and lifecycle (create/update/delete, membership, roles, aliases, bridge linking). |+| Gateway | `gateway/` (backend) + top-level `gateway/` (SPA) | Management/control-plane API and the operator dashboard that consumes it. |+| Persistence | `db/` | PostgreSQL via SQLAlchemy async; table models in `db/models.py`, query logic in `db/stores/`. |+| Homeserver admin | `matrix_admin.py` | Server-side homeserver operations: account registration, room create/invite/kick/delete. |++### The desktop app (switchdash)++`dash/` is a local-first Electron desktop app (an open-source fork; see+`dash/NOTICE`) for managing the local coding-agent sessions that participate in+Switch — which rooms an agent belongs to, its config, and session scheduling+(e.g. auto-starting a session when a Slack user addresses an agent that has no+live session). It is a convenience tool for running local agents, not a required+path — agents connect to the Agent Bridge directly over MCP or HTTP. It has its+own architecture docs under `dash/agents/`.++---++## 3. Domain model++The relational schema is defined in+[`core/switch_core/db/models.py`](../core/switch_core/db/models.py) (SQLAlchemy+`DeclarativeBase`). The core objects:++- **User** — a human principal; `role == "admin"` is a global authorization+ bypass. **ExternalUser** maps a platform identity (Slack/etc.) to a puppet.+- **Agent** — a registered AI agent, owned by a User. An agent inherits exactly+ its owner's permissions. **AgentSession** / **AgentRuntimeState** track a live+ session and its surfaced state (working / needs-input).+- **ApiKey** — a hashed credential, of type `"agent"` or `"registration"`.+- **Client** / **ClientRoom** — the Matrix client backing each participant and+ its room memberships.+- **Room** — a Matrix room plus Switch metadata (channel type, bridge link,+ instructions, visibility, protection/observe config). **RoomGroup** and+ **RoomLink** provide navigation grouping and directed room-to-room pointers.+- **RoomRole** / **RoleLease** — assumable, optionally exclusive room roles; a+ lease tracks the current holder.+- **Task** — the task-protocol record (`pending` → `ongoing` → `finalised` /+ `cancelled`).+- **Reference** / **Document** / **Package** — the attachable resource library+ (external pointers, internal docs, and bundles), each with independent+ read/write visibility.+- **CollaborationBridge** — configured external chat bridges.+- **BridgeMessageMap** — correlates a Matrix event with its external-platform+ post (for edits, threading, and loop prevention).+- **Tool** / **Model** / **Skill** — capabilities attached to agents, consulted+ during mediation. **FeatureFlag** — runtime toggles.++---++## 4. Key flows++### 4.1 Agent registration & connection++1. An agent calls `POST /agents` with a **registration token** (an `ApiKey` of+ type `"registration"`) and receives its own `{id, api_key}`+ ([`bridges/agent/api/handlers.py`](../core/switch_core/bridges/agent/api/handlers.py)).+ Known-agent types (e.g. `claude-code`) register via `POST /agents/register-known`.+2. All later calls present the agent API key as a `Bearer` token. The+ `BearerAuthMiddleware` ([`bridges/agent/auth.py`](../core/switch_core/bridges/agent/auth.py))+ SHA-256-hashes the token, looks it up in `ApiKeyStore`, and resolves the+ `Agent` onto the request scope.+3. Over MCP, the agent calls `connect_to_room`, which binds its MCP session to a+ room. Events are then delivered by **long-polling** (see 4.3).++### 4.2 Inbound message: external platform → agent++```mermaid+sequenceDiagram+ participant P as External platform+ participant A as Adapter (slack/…)+ participant BC as BridgeCore+ participant PU as Puppet Matrix client+ participant MX as Matrix room+ participant AC as AgentClient+ participant AG as Agent (MCP/HTTP)++ P->>A: message event (WebSocket / HTTP push)+ A->>BC: on_message(InboundMessage)+ BC->>BC: resolve/auto-create room, ensure puppet+ BC->>PU: send translated message+ PU->>MX: Matrix m.room.message+ MX-->>AC: sync event+ AC->>AC: is this addressed to my agent?+ AC-->>AG: enqueue AgentEvent (delivered on long-poll)+```++Inbound messages do **not** arrive through the `/collab` HTTP app (that app only+does bridge CRUD). Each adapter owns its transport:+Slack (Socket Mode WebSocket), Mattermost (WebSocket), and Discord (Gateway+WebSocket) hold **authenticated outbound connections**; Teams is the exception —+it self-hosts an HTTP listener (default port 3978) for Bot Framework activities+and Graph notifications.+[`bridges/collaboration/bridge_core.py`](../core/switch_core/bridges/collaboration/bridge_core.py)+translates the event, looks up or lazily creates the room for the channel,+ensures a **puppet** Matrix client exists for the external sender, and posts into+Matrix through it. `AgentClient`+([`clients/agent_client.py`](../core/switch_core/clients/agent_client.py))+observes the room over Matrix sync, decides whether the message addresses its+agent (by `@name`, room alias, or a held role), and enqueues an `AgentEvent`.++The outbound direction is symmetric: a `BridgeClient` observes agent messages in+the room and `BridgeCore.handle_outbound_message` relays them back out under the+agent's name/icon, preserving threads and attachments.++### 4.3 Event delivery & mediation++- **Delivery is long-poll, not push.** `ProtocolService`+ ([`bridges/agent/protocol/service.py`](../core/switch_core/bridges/agent/protocol/service.py))+ enqueues outbound events onto an in-memory per-agent, per-room `EventQueue`+ ([`protocol/event_queue.py`](../core/switch_core/bridges/agent/protocol/event_queue.py)),+ plus a separate **notification** stream restricted to addressed messages, task+ events, and opted-in room-joins. Agents drain these via+ `GET /agents/{id}/events` / `.../notifications` (returning `204` on timeout).+- **Mediation is synchronous.** The bridge exposes+ `POST /agents/.../mediation/{pre-tool-call,pre-llm-request,post-tool-result,post-llm-response}`.+ `RequestTracker`+ ([`bridges/agent/request_tracker.py`](../core/switch_core/bridges/agent/request_tracker.py))+ registers a future per request; the `ResourceManagerClient`+ ([`clients/resource_manager_client.py`](../core/switch_core/clients/resource_manager_client.py))+ evaluates the request (e.g. tool/model access against the agent's attached+ capabilities) and resolves the verdict. A room-level protection verdict path+ exists in the bridge but is not yet fully wired (`handle_protection_verdict`+ is gated pending protection setup).++### 4.4 In-room commands++Humans and agents can issue `!`-commands in a room (e.g. `!help`, `!list-agents`,+`!invite-agent`, `!set-alias`, session controls like `!reset`). These are defined+in [`bridges/agent/commands.py`](../core/switch_core/bridges/agent/commands.py);+admin-owned commands are executed by the `AdminClient`, the rest by the agents+themselves.++### 4.5 Room provisioning & lifecycle++`RoomService.create_room`+([`core/switch_core/room_service.py`](../core/switch_core/room_service.py)) is the+provisioning primitive: it validates attachments, (optionally) creates or+resolves the external channel on a bridge, creates the Matrix room via+`MatrixAdmin`, persists the `Room` row, defines roles and seeds aliases, then+invites the bridge client (first, so it replicates before agents post), the+agent clients, and the system clients. Membership is by ordinary Matrix+invitations that clients auto-accept. The service also handles update, delete,+archiving, membership changes, and moving a room between bridges.++---++## 5. Entry points / request surface++Everything ingress-facing, and where to find it:++| Entry point | Path / transport | Auth | Code |+|-------------|------------------|------|------|+| Agent Bridge API | `/agents/*` (HTTP) | Bearer (agent API key / registration token) | `bridges/agent/api/`, `auth.py` |+| MCP server | `/mcp` (HTTP, FastMCP) | Bearer | `bridges/agent/mcp/server.py` |+| Health | `/health` | public | `main.py` |+| Collaboration admin | `/collab/bridges` | (bridge CRUD) | `bridges/collaboration/api.py` |+| Gateway API | `/gateway/*` | cookie JWT (`switch_auth`) | `gateway/app.py`, `gateway/auth.py` |+| Platform ingress | adapter transports (Slack/MM/Discord WebSocket; Teams HTTP :3978) | platform token / Teams JWT+HMAC | `bridges/collaboration/*/adapter.py` |++Auth-bypass path prefixes for the Bearer middleware are enumerated in+`bridges/agent/auth.py` (`PUBLIC_PATH_PREFIXES`): `/health`, `/.well-known`,+`/collab`, `/gateway` (the gateway uses its own cookie-based auth).++---++## 6. Identity & permissions (design)++- **Agent authentication** — Bearer middleware+ ([`bridges/agent/auth.py`](../core/switch_core/bridges/agent/auth.py)) accepts+ two credential kinds: an agent API key (SHA-256 hashed, looked up in+ `ApiKeyStore`) and a registration token (used only for the registration+ endpoint).+- **Gateway authentication** — cookie-based JWT+ ([`gateway/auth.py`](../core/switch_core/gateway/auth.py)): passwords hashed+ with bcrypt, a `switch_auth` HS256 cookie (`httponly`, `samesite=lax`),+ optional OIDC login, and a toggle to disable password login. A seeded admin+ user is created at startup from config.+- **Authorization** — a single pure-policy chokepoint,+ [`core/switch_core/authz.py`](../core/switch_core/authz.py). The subject is+ always a **user** principal; an agent-initiated request resolves to the+ agent's owner and inherits exactly that owner's permissions. `role == "admin"`+ is a global bypass. Owned entities (Rooms, References, Documents, Packages)+ carry independent `read_visibility` and `write_visibility` (`public` /+ `private`); the rule is uniform across them and only their *default*+ visibility differs. `authz` has no I/O, so it is trivially testable and call+ sites route through it (`require(...)`).+- **Room scoping** — an agent only receives events for, and can only act in,+ rooms it is a member of. Cross-room resource access is validated server-side+ (e.g. a room-document request checks the document is attached to the+ requesting room).++---++## 7. Data & state++- **Database** — PostgreSQL over SQLAlchemy async. Table models in+ [`db/models.py`](../core/switch_core/db/models.py); all query logic is isolated+ in per-entity stores under [`db/stores/`](../core/switch_core/db/stores/).+ Schema changes are Alembic migrations (`core/switch_core/migrations/`).+- **Configuration** — all runtime config comes from environment variables via a+ Pydantic `BaseSettings` model+ ([`config.py`](../core/switch_core/config.py)); `.env.example` documents the+ required variables. No secrets are committed to the repository.+- **Secrets at rest** — external bridge tokens are encrypted with Fernet before+ being stored, using a key derived from a service secret+ ([`crypto.py`](../core/switch_core/crypto.py)).+- **Matrix state** — each client persists its sync token and access token via+ `ClientStore` so it can resume across restarts.++---++## 8. Code map++A quick index for navigation:++| Area | Directory / module |+|------|--------------------|+| App assembly & startup | `core/switch_core/main.py` |+| Configuration | `core/switch_core/config.py` |+| Authorization policy | `core/switch_core/authz.py` |+| Token encryption | `core/switch_core/crypto.py` |+| Agent Bridge (API, MCP, protocol, auth, commands) | `core/switch_core/bridges/agent/` |+| Collaboration bridges (adapters, core, lifecycle) | `core/switch_core/bridges/collaboration/` |+| Resource bridge | `core/switch_core/bridges/resource/` |+| Matrix clients | `core/switch_core/clients/` |+| Room provisioning & lifecycle | `core/switch_core/room_service.py`, `rooms_yaml.py` |+| Homeserver admin | `core/switch_core/matrix_admin.py` |+| Per-room aliases | `core/switch_core/aliases.py` |+| Database models & stores | `core/switch_core/db/` |+| Migrations | `core/switch_core/migrations/` |+| Gateway API (backend) | `core/switch_core/gateway/` |+| Operator dashboard (SPA) | `gateway/` (top level) |+| Desktop app | `dash/` |++---++## Notes on current state++A few things are intentionally partial and worth knowing when reading the code:++- **`observe` client type** is declared as a system client type but is not yet+ implemented (custom `com.switch.observe.*` events are logged as unsupported).+- **Room-level protection verdicts** — the mediation request/response path is in+ place (tool/model access checks); the broader per-room protection pipeline is+ still being wired (`handle_protection_verdict` is gated).++### Planned: centralized security & observability++A key part of the intended design — **not yet implemented** — is a centralized+**security and observability protection** layer built on top of Switch. Because+every agent connects through Switch and all activity flows across the Matrix+bus, Switch is the natural single point at which such protection can be applied+**uniformly to all connected agents**, rather than configured per-agent: e.g.+mediating and authorizing agents' tool and LLM calls and capturing a consistent+observability/audit trail centrally. The low-level mediation primitives exist+today (see §4.3), but this centralized cross-agent protection-and-observability+layer is a planned direction and is not yet part of the implemented design.