# corsairdev/corsair architecture

> Architecture diagram of the GitHub repository corsairdev/corsair, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corsairdev/corsair
- Repository: https://github.com/corsairdev/corsair

## Overview

1. **This is a TypeScript monorepo for an integration platform, not a single app.**  
   The main product is Corsair: a shared “integration layer” that sits between agents and third-party SaaS APIs. The repo also contains the marketing site, docs, CLI, local studio, demos, and many provider-specific packages.

2. **The core runtime lives in `packages/corsair`.**  
   This package is the platform boundary: auth, encryption, permissions, tenant resolution, connect flows, webhooks, hub/approval handling, and database access. It also exposes client entry points and adapters for management APIs. If you draw one central box, this is it.

3. **Provider support is implemented as one package per integration under `packages/*`.**  
   Examples include Slack, GitHub, Gmail, HubSpot, Linear, Stripe, etc. Most follow the same shape: `client.ts`, `endpoints/`, `webhooks/`, `schema/`, plus tests. These packages are leaf adapters that translate Corsair’s internal flow into each vendor’s API and event model.

4. **Each integration package separates read/write API calls from webhook ingestion.**  
   The `endpoints/` layer defines typed API operations; `webhooks/` defines event handlers, tenant matching, and provider-specific verification or challenge logic; `schema/` defines persistence for credentials, subscriptions, and plugin state. This is the main boundary between outbound API calls and inbound event processing.

5. **Permissions and approval are a central data flow.**  
   Agent tool calls are evaluated against per-integration mode rules like open, cautious, strict, and readonly. If an action needs approval, Corsair writes a permission request to its database and returns a review link. The agent never gets direct access to credentials; the platform resolves secrets internally at call time.

6. **Multi-tenancy is first-class.**  
   The core package and many plugin packages include tenant-matcher logic, tenant-specific credential storage, and tenant-scoped webhook handling. Requests can be bound to a tenant so credentials, permissions, and stored data do not cross-contaminate across organizations.

7. **Webhooks converge on shared handling infrastructure.**  
   Each provider package exposes typed webhook handlers, but they all plug into Corsair’s shared webhook processing path. The core package includes webhook binding, signature/tenant resolution, and replay/duplication guards. The README’s “single endpoint” model is reflected throughout the repo.

8. **Agent-facing consumption happens through MCP and SDK layers.**  
   `packages/mcp` provides MCP server adapters for Anthropic/Claude, OpenAI, Mastra, Vercel AI, Ollama, etc. `packages/ui` contains reusable tool/permission UI snippets. The `demo/mcp` and `demo/minimal` apps show how agents connect to Corsair, call tools, and trigger approvals.

9. **Operational tooling is split into CLI, studio, and demos.**  
   `packages/cli` handles setup, auth, subscribing integrations, credential provisioning, and renewal flows. `packages/studio` is a local operator UI with its own server/router and React front end for inspecting plugins, permissions, tenants, chats, and scripts. `demo/testing` is a full Next.js test harness with TRPC, Inngest, webhook routes, and database migrations.

10. **The public website and docs are separate products with their own backend concerns.**  
   `www` is the marketing/OSS site built on Next.js, with auth, TRPC, webhooks, revalidation, Sanity-backed blog content, and its own database schema for OSS/integration tracking. `docs` is MDX documentation for the platform and plugins, and many plugin docs are generated from package metadata.

11. **Data stores are used for platform state, not for vendor content itself.**  
   The core package uses a Kysely-backed database layer for credentials, permissions, tenant links, and hub state; app-level projects like `www` and `demo/testing` use Drizzle for their own tables. The important architectural point is that persistent state is centralized in Corsair’s DB layer, while provider APIs remain external systems.

12. **Build and generation are monorepo-wide concerns.**  
   The repo uses pnpm workspaces, Turbo, tsup, Jest, and Biome/Prettier-style tooling. Scripts generate plugin docs, scaffold integrations, validate packages, and publish changed artifacts. That means most architecture is code-generated or convention-driven across the provider packages, rather than hand-wired one by one.

13. **A useful diagram should show four edge layers around the core.**  
   Put external SaaS APIs/webhooks on one side, agent runtimes/MCP clients on another, the Corsair core/control plane in the center, and operational surfaces (CLI, Studio, website/docs, demos) around it. The key flows are: agent tool call → permission/auth resolution → provider API call, and provider webhook → shared webhook handler → tenant-scoped state update.

Main entry points: [`packages/corsair`](https://github.com/corsairdev/corsair/tree/main/packages/corsair) (Corsair), [`packages/airtable/webhooks`](https://github.com/corsairdev/corsair/tree/main/packages/airtable/webhooks) (Webhooks), [`packages`](https://github.com/corsairdev/corsair/tree/main/packages) (Integrations), [`packages/corsair/hub`](https://github.com/corsairdev/corsair/tree/main/packages/corsair/hub) (Hub)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control_plane["Corsair core"]
  node_corsair_core["Corsair<br/>platform core"]
  node_corsair_auth["Auth<br/>security"]
  node_corsair_permissions["Permissions<br/>approval policy"]
  node_corsair_tenants["Tenants<br/>multi-tenant routing"]
  node_corsair_management["Management API<br/>adapters"]
  node_corsair_hub["Hub<br/>delivery & connect"]
  node_corsair_db[("Database<br/>kysely persistence")]
  node_corsair_setup["Setup<br/>provisioning"]
  node_corsair_client["Client SDK<br/>client entrypoints"]
end

subgraph group_providers["Provider packages"]
  node_provider_packages["Integrations<br/>provider adapters"]
  node_provider_endpoints["Endpoints<br/>outbound API layer"]
  node_provider_webhooks["Webhooks<br/>inbound event layer"]
  node_provider_schema["Schemas<br/>integration state"]
end

subgraph group_agent_layer["Agent surface"]
  node_mcp_adapters["MCP adapters<br/>agent runtime bridge"]
  node_ui_helpers["UI helpers<br/>permission UI"]
end

subgraph group_ops_surface["Operational surfaces"]
  node_cli_tool["CLI<br/>operator tool"]
  node_studio_app["Studio<br/>local operator UI"]
  node_testing_demo["Testing demo<br/>full-stack harness"]
  node_mcp_demo["MCP demo<br/>agent demo"]
  node_docs_site["Docs"]
  node_www_site["Website<br/>next.js product site"]
end

subgraph group_external["External systems"]
  node_external_saas[("SaaS APIs<br/>external vendors")]
  node_external_webhooks["Webhook sources<br/>incoming events"]
end

node_mcp_adapters -->|"uses"| node_corsair_client
node_ui_helpers -->|"renders"| node_corsair_permissions
node_cli_tool -->|"operates"| node_corsair_core
node_studio_app -->|"inspects"| node_corsair_core
node_testing_demo -->|"integration path"| node_corsair_core
node_mcp_demo -->|"demonstrates"| node_mcp_adapters
node_docs_site -->|"documents"| node_corsair_core
node_www_site -->|"describes"| node_corsair_core
node_provider_packages -->|"contains"| node_provider_endpoints
node_provider_packages -->|"contains"| node_provider_webhooks
node_provider_packages -->|"contains"| node_provider_schema
node_provider_endpoints -->|"calls"| node_external_saas
node_external_webhooks -->|"delivers"| node_provider_webhooks
node_provider_webhooks -->|"resolves tenant"| node_corsair_tenants
node_provider_webhooks -->|"routes through"| node_corsair_core
node_corsair_core -->|"delegates"| node_corsair_auth
node_corsair_core -->|"evaluates"| node_corsair_permissions
node_corsair_core -->|"scopes"| node_corsair_tenants
node_corsair_core -->|"exposes"| node_corsair_management
node_corsair_core -->|"drives"| node_corsair_hub
node_corsair_core -->|"persists to"| node_corsair_db
node_corsair_setup -->|"initializes"| node_corsair_db
node_corsair_hub -->|"binds"| node_external_webhooks

click node_corsair_core "https://github.com/corsairdev/corsair/tree/main/packages/corsair"
click node_corsair_auth "https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/auth"
click node_corsair_permissions "https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/permissions"
click node_corsair_tenants "https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/webhooks"
click node_corsair_management "https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/management"
click node_corsair_hub "https://github.com/corsairdev/corsair/tree/main/packages/corsair/hub"
click node_corsair_db "https://github.com/corsairdev/corsair/tree/main/packages/corsair/db"
click node_corsair_setup "https://github.com/corsairdev/corsair/tree/main/packages/corsair/setup"
click node_corsair_client "https://github.com/corsairdev/corsair/tree/main/packages/corsair/client"
click node_mcp_adapters "https://github.com/corsairdev/corsair/tree/main/packages/mcp/src/adapters"
click node_ui_helpers "https://github.com/corsairdev/corsair/tree/main/packages/ui/src"
click node_provider_packages "https://github.com/corsairdev/corsair/tree/main/packages"
click node_provider_endpoints "https://github.com/corsairdev/corsair/tree/main/packages/ahrefs/endpoints"
click node_provider_webhooks "https://github.com/corsairdev/corsair/tree/main/packages/airtable/webhooks"
click node_provider_schema "https://github.com/corsairdev/corsair/tree/main/packages/airtable/schema"
click node_cli_tool "https://github.com/corsairdev/corsair/tree/main/packages/cli/src"
click node_studio_app "https://github.com/corsairdev/corsair/tree/main/packages/studio/src"
click node_testing_demo "https://github.com/corsairdev/corsair/tree/main/demo/testing/src"
click node_mcp_demo "https://github.com/corsairdev/corsair/tree/main/demo/mcp"
click node_docs_site "https://github.com/corsairdev/corsair/tree/main/docs"
click node_www_site "https://github.com/corsairdev/corsair/tree/main/www"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_corsair_core,node_corsair_auth,node_corsair_permissions,node_corsair_tenants,node_corsair_management,node_corsair_hub,node_corsair_db,node_corsair_setup,node_corsair_client toneBlue
class node_provider_packages,node_provider_endpoints,node_provider_webhooks,node_provider_schema toneAmber
class node_mcp_adapters,node_ui_helpers toneMint
class node_cli_tool,node_studio_app,node_testing_demo,node_mcp_demo,node_docs_site,node_www_site toneRose
class node_external_saas,node_external_webhooks toneIndigo
```

## Components

### Corsair core

Shared runtime boundary for auth, permissions, tenants, webhooks, hub flows, and database access.

- [Corsair](https://github.com/corsairdev/corsair/tree/main/packages/corsair): platform core · Primary integration layer: auth, encryption, permissions, tenant resolution, connect, webhooks, hub state, and DB access. · `packages/corsair`
- [Auth](https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/auth): security · Key management, encryption, token exchange, plugin auth state, and auth error handling. · `packages/corsair/core/auth`
- [Permissions](https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/permissions): approval policy · Mode rules, approval messaging, and permission request handling for agent actions. · `packages/corsair/core/permissions`
- [Tenants](https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/webhooks): multi-tenant routing · Tenant provisioning, account lookup, tenant links, and webhook tenant matching utilities. · `packages/corsair/core/webhooks`
- [Management API](https://github.com/corsairdev/corsair/tree/main/packages/corsair/core/management): adapters · Management handlers and framework adapters for binding Corsair into apps like Next, Express, and Hono. · `packages/corsair/core/management`
- [Hub](https://github.com/corsairdev/corsair/tree/main/packages/corsair/hub): delivery & connect · Connect flows, signed delivery, replay protection, credentials delivery, and browser handoff paths. · `packages/corsair/hub`
- [Database](https://github.com/corsairdev/corsair/tree/main/packages/corsair/db): kysely persistence · Central platform state for credentials, permissions, tenant links, and hub records. · `packages/corsair/db`
- [Setup](https://github.com/corsairdev/corsair/tree/main/packages/corsair/setup): provisioning · Bootstrap, backfill, and platform setup routines that prepare integrations and state. · `packages/corsair/setup`
- [Client SDK](https://github.com/corsairdev/corsair/tree/main/packages/corsair/client): client entrypoints · Core and React client entrypoints for agent-side and app-side consumption. · `packages/corsair/client`

### Provider packages

Leaf integration packages that adapt Corsair flows to vendor APIs and webhook models.

- [Integrations](https://github.com/corsairdev/corsair/tree/main/packages): provider adapters · Convention-based packages for SaaS vendors, each mapping API endpoints and webhook events into Corsair. · `packages`
- [Endpoints](https://github.com/corsairdev/corsair/tree/main/packages/ahrefs/endpoints): outbound API layer · Typed read/write operations that call vendor APIs from integration packages. · `packages/ahrefs/endpoints`
- [Webhooks](https://github.com/corsairdev/corsair/tree/main/packages/airtable/webhooks): inbound event layer · Provider-specific webhook handlers, verification, tenant matching, and challenge logic. · `packages/airtable/webhooks`
- [Schemas](https://github.com/corsairdev/corsair/tree/main/packages/airtable/schema): integration state · Package-local persistence for credentials, subscriptions, and plugin-specific state. · `packages/airtable/schema`

### Agent surface

Agent-facing runtimes, SDKs, and UI helpers used to call tools and handle approvals.

- [MCP adapters](https://github.com/corsairdev/corsair/tree/main/packages/mcp/src/adapters): agent runtime bridge · Adapters that expose Corsair tools over MCP for Claude, OpenAI, Mastra, Vercel AI, Ollama, and related runtimes. · `packages/mcp/src/adapters`
- [UI helpers](https://github.com/corsairdev/corsair/tree/main/packages/ui/src): permission UI · Reusable permission and plugin UI snippets used by agent-facing surfaces. · `packages/ui/src`

### Operational surfaces

CLI, studio, demos, docs, and website products that exercise or present the platform.

- [CLI](https://github.com/corsairdev/corsair/tree/main/packages/cli/src): operator tool · Setup, auth, subscription, credential provisioning, and renewal commands for operators. · `packages/cli/src`
- [Studio](https://github.com/corsairdev/corsair/tree/main/packages/studio/src): local operator UI · Local server and React interface for inspecting plugins, tenants, permissions, chats, scripts, and database state. · `packages/studio/src`
- [Testing demo](https://github.com/corsairdev/corsair/tree/main/demo/testing/src): full-stack harness · Next.js harness that wires Corsair, TRPC, Inngest, webhook routes, and migrations for integration testing. · `demo/testing/src`
- [MCP demo](https://github.com/corsairdev/corsair/tree/main/demo/mcp): agent demo · Minimal examples showing agent tool calls, approvals, and webhook-driven flows through Corsair. · `demo/mcp`
- [Docs](https://github.com/corsairdev/corsair/tree/main/docs): mdx docs · Platform documentation, plugin docs, and generated guides for management, MCP, multi-tenancy, and webhooks. · `docs`
- [Website](https://github.com/corsairdev/corsair/tree/main/www): next.js product site · Marketing and OSS site with auth, TRPC, webhooks, revalidation, Sanity content, and its own database. · `www`

### External systems

Third-party SaaS APIs, webhook sources, and platform services outside the repo.

- **SaaS APIs**: external vendors · Third-party APIs such as Slack, GitHub, Gmail, HubSpot, Linear, Stripe, and others.
- **Webhook sources**: incoming events · External webhook senders that trigger provider-specific handlers and Corsair’s shared processing path.

## Connections

- MCP adapters → Client SDK: uses · MCP adapters consume Corsair client/tool definitions.
- UI helpers → Permissions: renders · UI snippets present permission and approval flows.
- CLI → Corsair: operates · CLI configures and drives core platform setup and subscriptions.
- Studio → Corsair: inspects · Studio reads and manages platform state and operations.
- Testing demo → Corsair: integration path · Demo app exercises Corsair through server routes and harness flows.
- MCP demo → MCP adapters: demonstrates · Demo shows MCP client/runtime integration paths.
- Docs → Corsair: documents · Docs explain core concepts, management, webhooks, and multi-tenancy.
- Website → Corsair: describes · Website content and OSS surfaces are built around the Corsair platform.
- Integrations → Endpoints: contains · Integration packages expose typed vendor API operations.
- Integrations → Webhooks: contains · Integration packages expose vendor-specific webhook handlers.
- Integrations → Schemas: contains · Integration packages maintain local persistence schemas.
- Endpoints → SaaS APIs: calls · Outbound requests go to third-party SaaS APIs.
- Webhook sources → Webhooks: delivers · Webhook payloads enter the provider-specific handler layer.
- Webhooks → Tenants: resolves tenant · Webhook handlers match incoming events to the correct tenant.
- Webhooks → Corsair: routes through · Provider handlers plug into Corsair’s shared webhook processing path.
- Corsair → Auth: delegates · Core runtime resolves secrets and auth at call time.
- Corsair → Permissions: evaluates · Core checks tool calls against approval and mode rules.
- Corsair → Tenants: scopes · Core binds requests, state, and webhooks to a tenant.
- Corsair → Management API: exposes · Core provides management endpoints and framework adapters.
- Corsair → Hub: drives · Core uses hub flows for connect, delivery, and replay protection.
- Corsair → Database: persists to · Core stores credentials, permissions, tenant links, and hub state.
- Setup → Database: initializes · Setup routines provision and backfill platform state.
- Hub → Webhook sources: binds · Hub-side webhook and delivery binding accepts external callbacks.
