How Is the Corsair Codebase Structured? A Complete Monorepo Guide

Corsair uses a pnpm-organized monorepo with a core engine in packages/corsair, plugin integrations in separate packages/<name> directories, and supporting tooling for docs, scripts, and a public website.

The Corsair codebase is an open-source integration platform built as a monorepo using pnpm workspaces. This architecture lets the team manage 70+ plugin packages, a unified client library, and supporting infrastructure from a single repository while keeping builds and publishes independent.

Monorepo Layout Overview

The top-level directory structure groups concerns into distinct folders. Each serves a specific purpose in the development lifecycle.

Directory	Purpose	Key File
packages/	Plugin integrations and core library	packages/corsair/core/constants.ts
www/	Public website (corsair.dev) and OSS dashboard	www/src/app/oss/README.md
explorer/	Catalog UI for plugin discovery	explorer/src/catalog.ts
scripts/	Code generation and automation utilities	scripts/generate-plugin.ts
docs/	MDX documentation including workflow guides	docs/workflows/overview.mdx
pnpm-workspace.yaml	Workspace package declarations	Source

Core Engine: packages/corsair/

The core engine lives in packages/corsair/ and exports the createCorsair factory from packages/corsair/index.ts. This package coordinates all cross-cutting concerns.

Provider Registry

All supported integrations are enumerated in packages/corsair/core/constants.ts:

export const BaseProviders = [ 'slack', 'gmail', /* … */ ] as const;
export const ProviderDisplayNames = { slack: 'Slack', gmail: 'Gmail', /* … */ } as const;

These constants drive plugin registration. The core uses formatProviderDisplayName to resolve human-readable names from provider keys.

Tenant & Authentication

The core handles multi-tenant credentials, OAuth flows, token caching, and permission checks. Key modules include:

• oauth.ts — OAuth implementation
• orm.ts — database layer for credential storage
• permissions/ — access control logic

Client API Factory

packages/corsair/client/index.ts builds a typed client exposing each plugin as corsair.<provider>.api.*:

import { createCorsair } from 'corsair';

const corsair = createCorsair({
  apiKey: process.env.CORSAIR_API_KEY!,
  hub: { apiKey: process.env.CORSAIR_HUB_KEY! },
});

// Call any plugin method through the typed proxy
const channels = await corsair.slack.api.conversations.list({ limit: 10 });

Webhooks & Tunnel System

The webhooks/ directory contains helpers for processing incoming webhooks. The tunnel/ subdirectory implements a secure credential delivery system for browser-based authentication flows.

Workflow Engine

Durable, multi-step automations are defined in hub.ts and exposed via corsair.workflows:

const run = await corsair.workflows.run('welcome-email', {
  payload: { userId: '12345' },
});
const result = await corsair.workflows.get(run.id);

The runtime model is documented in docs/workflows/overview.mdx.

Plugin Architecture: packages/<name>/

Each plugin integration lives in its own folder under packages/. All plugins share a standardized structure:

• src/ — API implementation
• package.json — package metadata, dependencies, build config
• tsconfig.json — TypeScript settings inheriting from workspace

Examples include packages/slack/, packages/gmail/, and packages/zoominfo/. The generate:plugin script automates scaffolding new integrations.

Supporting Infrastructure

Website & OSS Dashboard (www/)

The public-facing site and contributor dashboard are Next.js applications. The OSS dashboard source lives at www/src/app/oss/.

Plugin Catalog (explorer/)

A lightweight UI for browsing available integrations, consumed by the documentation site.

Build Tooling (scripts/)

• generate-plugin.ts — scaffolds new plugin directories and updates constants.ts
• Publishing and PR review automation scripts

Documentation (docs/)

MDX-based docs covering workflows, provider setup, and API reference. The workflows/overview.mdx file explains the durable execution model.

Development Workflow

All packages use TypeScript 5.9.3 and Zod for schema validation, declared in pnpm-workspace.yaml. Standard commands:

pnpm install           # link workspace packages

pnpm lint              # biome across monorepo

pnpm typecheck         # verify all packages

pnpm build             # compile core and plugins

pnpm test              # Jest test suite

pnpm generate:plugin   # scaffold new integration

Key Files Reference

File	Role
[packages/corsair/core/constants.ts](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts)	Master provider registry
[packages/corsair/index.ts](https://github.com/corsairdev/corsair/blob/main/packages/corsair/index.ts)	createCorsair factory
[packages/corsair/hub.ts](https://github.com/corsairdev/corsair/blob/main/packages/corsair/hub.ts)	Workflow client implementation
[pnpm-workspace.yaml](https://github.com/corsairdev/corsair/blob/main/pnpm-workspace.yaml)	Workspace configuration
[AGENTS.md](https://github.com/corsairdev/corsair/blob/main/AGENTS.md)	Repository quick-start guide

Summary

• Corsair is a pnpm monorepo with clear separation between core engine, plugins, and infrastructure
• Core engine (packages/corsair/) provides provider registry, auth, webhooks, workflows, and client factory
• Plugin packages (packages/<name>/) implement 70+ integrations with standardized structure
• Supporting directories handle docs, website, catalog UI, and automation scripts
• Shared toolchain uses TypeScript 5.9.3, Zod, and Jest across all packages

Frequently Asked Questions

How does Corsair manage dependencies across 70+ packages?

The pnpm-workspace.yaml file declares all workspace packages, enabling pnpm to link them together. Shared dependencies like TypeScript and Zod are defined once and inherited across packages, while each plugin maintains its own specific dependencies in its package.json.

What file should I read first to understand the Corsair codebase structure?

Start with [AGENTS.md](https://github.com/corsairdev/corsair/blob/main/AGENTS.md) at the repository root. This file provides a concise high-level overview of the layout, common commands, and where to find specific components before diving into packages/corsair/core/constants.ts for the provider registry.

How do I add a new integration plugin to Corsair?

Run pnpm generate:plugin from the repository root. This script creates a new folder under packages/, scaffolds the standard source structure, and automatically updates packages/corsair/core/constants.ts to register the new provider in the system.

Where is the workflow runtime implemented in Corsair?

The workflow client API is implemented in [packages/corsair/hub.ts](https://github.com/corsairdev/corsair/blob/main/packages/corsair/hub.ts), which exposes corsair.workflows.run and related methods. The conceptual runtime model is documented in docs/workflows/overview.mdx.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}