# How Is the Corsair Codebase Structured? A Complete Monorepo Guide

> Explore the Corsair monorepo structure. Discover how pnpm organizes the core engine, plugin integrations, and supporting tools within the corsairdev/corsair repository for efficient development.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: internals
- Published: 2026-09-01

---

**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`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts) |
| `www/` | Public website (`corsair.dev`) and OSS dashboard | [`www/src/app/oss/README.md`](https://github.com/corsairdev/corsair/blob/main/www/src/app/oss/README.md) |
| `explorer/` | Catalog UI for plugin discovery | [`explorer/src/catalog.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/catalog.ts) |
| `scripts/` | Code generation and automation utilities | [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) |
| `docs/` | MDX documentation including workflow guides | `docs/workflows/overview.mdx` |
| [`pnpm-workspace.yaml`](https://github.com/corsairdev/corsair/blob/main/pnpm-workspace.yaml) | Workspace package declarations | [Source](https://github.com/corsairdev/corsair/blob/main/pnpm-workspace.yaml) |

## Core Engine: `packages/corsair/`

The **core engine** lives in `packages/corsair/` and exports the `createCorsair` factory from [`packages/corsair/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/index.ts). This package coordinates all cross-cutting concerns.

### Provider Registry

All supported integrations are enumerated in [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts):

```typescript
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`](https://github.com/corsairdev/corsair/blob/main/oauth.ts) — OAuth implementation
- [`orm.ts`](https://github.com/corsairdev/corsair/blob/main/orm.ts) — database layer for credential storage
- `permissions/` — access control logic

### Client API Factory

[`packages/corsair/client/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/client/index.ts) builds a typed client exposing each plugin as `corsair.<provider>.api.*`:

```typescript
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`](https://github.com/corsairdev/corsair/blob/main/hub.ts) and exposed via `corsair.workflows`:

```typescript
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`](https://github.com/corsairdev/corsair/blob/main/package.json) — package metadata, dependencies, build config
- [`tsconfig.json`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/generate-plugin.ts) — scaffolds new plugin directories and updates [`constants.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/pnpm-workspace.yaml). Standard commands:

```bash
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)](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)](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)](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)](https://github.com/corsairdev/corsair/blob/main/pnpm-workspace.yaml) | Workspace configuration |
| [[`AGENTS.md`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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)](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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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)](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`.