core/docs/ARCHITECTURE.md

Switchboard Core — Architecture

Switchboard Core is a self-hosted extension platform. It provides identity, teams, permissions, storage, workflows, notifications, and a package system. Everything else — chat, AI providers, personas, knowledge bases, notes, tools — ships as installable extensions.

Design Principles

KISS. Every kernel feature earns its place by being required by two or more extensions or by being impossible to implement outside the kernel. When in doubt, leave it out and let an extension handle it.

Store interface discipline. All database access flows through the store interface layer. No raw SQL in handlers, middleware, or sandbox code. PostgreSQL and SQLite are first-class peers — every query compiles and passes tests on both.

Two-track execution. Go for platform operations (auth, migrations, package lifecycle). Starlark for custom admin/team logic (extension hooks, workflow automation, triggers). The boundary is permanent.

Extensions all the way down. The platform ships with a kernel and a package installer. Surfaces (UI pages), tools, filters, triggers, and providers are all packages. The editor, chat, and admin UI will themselves be installable surface packages.

Kernel Components

Identity & Auth

Users, refresh tokens, OIDC, mTLS, builtin password auth. The kernel owns the user lifecycle because extensions need a stable identity to key permissions, settings, and data against.

Auth modes: builtin (password), mtls (client cert), oidc (Keycloak et al.). Mode is set at deploy time via AUTH_MODE env var.

Teams & Groups

Teams provide horizontal isolation — users see only their team's resources. Groups provide vertical permissions — what actions a user can perform.

The Everyone group (well-known UUID) grants baseline permissions to all authenticated users without an explicit membership row. Current kernel permissions: extension.use, extension.install, workflow.create, workflow.submit, admin.view, token.unlimited.

Packages

The unified registry for all installable content. A package is a surface (routable UI page), an extension (Starlark hooks/tools/pipes), a library (shared dependency), or a workflow definition. Package types:

Type	What it provides
surface	A routable page rendered in the shell viewport
extension	Starlark hooks, tools, API routes, DB tables
full	Both surface and extension
workflow	Bundled workflow definition
library	Shared code imported by other packages

Tiers: browser (JS only), starlark (sandboxed server-side), sidecar (container, future).

Starlark Sandbox

Extensions declare capabilities in their manifest. The admin grants or denies each capability. At runtime the sandbox injects only the modules the extension has been granted:

• db — namespaced table CRUD (ext_{pkg_id}_{table})
• http — SSRF-safe outbound HTTP
• notifications — push notifications to users
• secrets — read connection credentials from the vault
• api — register extension HTTP routes (/s/:slug/api/*path)

The sandbox cannot spawn goroutines, access the filesystem, or import arbitrary Go packages. It runs with a CPU budget and memory ceiling.

Workflows

Staged processes with form collection, human review, and webhooks. Workflow definitions live in the kernel because they orchestrate teams, permissions, and notifications — all kernel concerns.

Stages support four modes: form_only, form_chat, review, custom. The custom mode delegates rendering to a surface package, proving the extension stack end-to-end.

Workflow instances are being redesigned. The old channel-based model (v0.38) is removed. New instance storage will use extension data tables or a dedicated kernel table — TBD in v0.2.0.

Connections

Scoped credential storage for extensions. Global (admin-managed), team, or personal scope. Secrets are AES-256-GCM encrypted at rest using the platform encryption key or the user's vault key (BYOK).

Connection types are declared by packages. Multiple packages can share a connection type (e.g., both a GitHub extension and a CI extension declare type github).

Triggers (planned — v0.2.0)

Three trigger types invoke extension Starlark handlers:

Trigger	Source	Kernel primitive
time	Cron expression	Ticker goroutine + dispatch
webhook	Inbound HTTP	Ext API route sugar
event	Internal event bus	Subscription registry

All three converge to sandbox.Call(handler, triggerContext). The extension doesn't know or care how it was invoked.

Tasks (the old scheduler) are rebuilt as a Starlark extension on top of these three primitives. This validates the extension stack and removes ~3,400 lines from the kernel.

Event Bus

Server-sent events to WebSocket clients. Kernel prefixes: user.*, team.*, workflow.*, notification.*, presence.*, extension.*, admin.*, system.*.

Extensions will subscribe to event patterns at install time (v0.2.0). Match expressions start as exact strings, grow to globs later.

Storage & Notifications

Object storage: PVC (local disk) or S3-compatible. Used by extensions for file uploads, package assets, and blob storage.

Notifications: In-app notification bell with per-type preferences. Extension packages can push notifications via the sandbox module.

Data Layer

Dual-store: PostgreSQL (production) and SQLite (dev/test/edge). 27 kernel tables across 9 migration files per dialect:

Migration	Tables
001_core	users, refresh_tokens, platform_policies, global_settings, user_presence, oidc_auth_state
002_teams	teams, team_members, groups, group_members
003_packages	packages, package_user_settings, extension_permissions, ext_data_tables
004_connections	ext_connections, ext_dependencies, resource_grants
005_notifications	notifications, notification_preferences
006_audit	audit_log
007_workflows	workflows, workflow_stages, workflow_versions
008_ha	ws_tickets, rate_limit_counters

SQLite parity rules: boolToInt for boolean binding, store.NewID() for INSERT RETURNING, no NULLS FIRST, no boolean literals, no $N reuse, database.ST()/database.SNT() wrappers for time scanning.

Frontend

Preact (3KB) + htm (tagged template literals). No build step, no bundler (except CM6 via esbuild). IIFE/global-namespace pattern with sb.register()/sb.ns().

The shell loads surfaces into a viewport. Extensions use window.html and window.preact directly. Hooks via window.hooks. Vendor libs (marked.js, DOMPurify, KaTeX, CodeMirror 6) baked into the image.

Deployment

Single Docker image: Go binary + migrations + frontend assets + vendor libs. Kubernetes deployment with 3-node PG cluster. CI via Gitea Actions with DaemonSet DinD runners testing both PG and SQLite pipelines.

Registry: registry.gobha.me:5000/xcaliber/switchboard-core Namespace: gobha-ai-chat