Skip to main content

Architecture

System diagram​

architecture
┌─────────────────────────────────────────────────────────────┐
│  Your AI Agent (Claude, ChatGPT, Claude Code, any MCP client)│
└────────────────────────────┬────────────────────────────────┘
                             │ MCP Protocol (streamable-http)
┌────────────────────────────▼────────────────────────────────┐
│  SignalPilot Gateway                                         │
│  ┌────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│  │ Governance │ │ Schema       │ │ dbt Project           │ │
│  │ • LIMIT    │ │ • DDL        │ │ • Map / Validate      │ │
│  │ • DDL block│ │ • Explore    │ │ • Model verification  │ │
│  │ • Audit    │ │ • Join paths │ │ • Date boundaries     │ │
│  └────────────┘ └──────────────┘ └───────────────────────┘ │
└────────────────────────────┬────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐        ┌──────────┐        ┌──────────┐
   │ DuckDB  │        │ Postgres │        │Snowflake │
   └─────────┘        └──────────┘        └──────────┘

Component table​

ComponentDescription
GatewayFastAPI server exposing 62 MCP tools over streamable-http. Port 3300.
Chat workerSeparate process, same image as the gateway. Claims and runs chat and agent jobs.
EngineSQL governance and multi-dialect execution. Covers PostgreSQL, MySQL, SQLite, SQL Server, Snowflake, Databricks, BigQuery, and more.
Connectors12 database connectors with pooling and SSH tunneling: DuckDB, PostgreSQL, MySQL, SQLite, SQL Server, Snowflake, Databricks, BigQuery, Redshift, ClickHouse, Trino, and Xata.
StorePostgres-backed credential, connection, knowledge, and audit storage with Fernet encryption.
AuthClerk JWT verification (cloud) or API key auth (local and cloud). Org-scoped with brute-force protection.
Web UINext.js 16 frontend on port 3200. Connection management, chat, notebooks, query history, dashboards.
Network validationSSRF protection with DNS rebinding defense for cloud warehouse connections.
SandboxesPer-session isolated microVMs for notebooks and chat. One shared notebook container in local mode.
PluginClaude Code plugin: 24 skills and 2 verifier agents. Runs outside the gateway, local to Claude Code.
sp-sandboxSandbox manager for DuckDB and SQLite queries over local files.

Gateway responsibilities​

The gateway is the enforcement boundary. Every MCP tool call passes through:

  1. Auth: validate API key or Clerk JWT, resolve org and tenant
  2. Rate limiter: per-IP, per-key, per-org throttling
  3. SQL governance: parse, block DDL/DML, deny dangerous functions, inject LIMIT
  4. Query execution: route to the correct connector
  5. Audit: write a log entry with PII-redacted SQL

The web UI is a separate process. It calls the gateway's REST API. It does not have direct database access.

MCP transport​

SignalPilot uses streamable-http, the current MCP standard. The endpoint is:

  • /mcp (canonical)
  • / (backward compatibility)

MCP tool calls are stateless per request. The gateway does not keep a websocket or a server-sent event stream open between tool calls, so a restart mid-session is safe. (The authenticated /api/metrics route is a separate server-sent event stream for monitoring; see Operations.)

Deployment modes​

Self-hosted (Docker Compose)​

self-hosted
$ docker compose up -d
# Web UI:   http://localhost:3200
# Gateway:  http://localhost:3300

One docker-compose.yml brings up the whole stack. Auth is API-key based. No Clerk required.

docker compose stack
Docker Compose
  ├── web                  (Next.js, port 3200)
  ├── gateway              (FastAPI, port 3300)
  ├── gateway-chat-worker  (chat and agent jobs)
  ├── notebook             (shared notebook container, port 2718)
  ├── db                   (Postgres, host port 5601)
  ├── minio + minio-init   (object storage, ports 9000/9001)
  ├── mailpit              (email catcher, port 8025)
  ├── sandbox              (DuckDB/SQLite sandbox manager)
  └── eval-object-proxy    (read-only bridge on the eval network)

All ports bind to loopback. See Self-host with Docker Compose.

Cloud mode​

cloud mode
Clerk Auth  →  Next.js Frontend  →  Gateway  →  Cloud warehouses
                                        |
                                  API Key Auth (org-scoped)
                                        |
                                  Hosted sandboxes (one microVM per session)

Multi-tenant. Clerk JWT for SSO. Org-scoped API keys. Managed history, dashboards, encrypted credential storage. Notebooks and chat run in per-session isolated microVMs.

Security architecture​

See Security for the full breakdown. Summary:

  • Read-only: DDL/DML blocked at parse time
  • Tenant isolation: API keys are org-scoped; cross-tenant access impossible at the data layer
  • Encryption at rest: Fernet/MultiFernet for credentials; one-way SHA-256 hashes for high-entropy API keys
  • Audit logging: every query logged, SQL literals PII-redacted
  • Non-root containers: gateway runs as UID 10001
  • SSRF protection: cloud warehouse hostnames validated against an allow-list
  • Sandbox isolation: one microVM per session with restricted egress and fixed CPU and memory

Why governance is server-side​

The governance engine runs in the gateway, not in the AI agent. This means:

  • Governance applies regardless of which client calls the MCP tools
  • The agent cannot bypass governance by modifying its prompts
  • Audit logs are authoritative. They reflect what actually ran, not what the agent claimed