# How Corsair Organizes Its Components: A Deep Dive Into the Repository Architecture

> Discover how Corsair organizes its components within the corsairdev/corsair monorepo. Explore the repository architecture and distinct directory structures for plugins, tooling, and more.

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

---

**Corsair uses a monorepo structure that cleanly separates the core integration engine, individual plugin packages, developer tooling, and public website into distinct top-level directories.**

The corsairdev/corsair repository is organized as a **modular TypeScript monorepo** designed to scale across approximately 70 third-party integrations. This guide examines how each component is structured, where critical files live, and how the architecture enables maintainable plugin development.

## Core Engine: The Universal Runtime (`packages/corsair/`)

The **core package** provides the generic runtime that all plugins extend. Located at `packages/corsair/`, it handles provider registration, display name resolution, OAuth flows, and multi-tenant webhook delivery.

### Provider Registration and Constants

The master list of all supported integrations lives in [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts). This file exports `BaseProviders`, a constant array enumerating every provider Corsair supports:

```ts
// packages/corsair/core/constants.ts
export const BaseProviders = [
  'dropboxsign', 'ably', 'abstract', /* … 70+ more … */ 'zoominfo',
] as const;

```

The same file provides `formatProviderDisplayName()`, which maps provider keys to human-readable names for UI rendering.

### OAuth and Multi-Tenant Infrastructure

- **[`packages/corsair/oauth.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/oauth.ts)** – Manages OAuth token acquisition, refresh, and secure storage
- **`packages/corsair/tunnel/`** – Coordinates multi-tenant webhook delivery
- **`packages/corsair/webhooks/`** – Handles webhook routing and tenant linking

The core exports its public API through [`packages/corsair/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/index.ts), which exposes the `Corsair` class used by all consumers:

```ts
import { Corsair } from '@corsairdev/corsair';

const corsair = new Corsair({
  // Global configuration: API key store, logger, etc.
});

```

## Plugin Packages: Isolated Integration Adapters (`packages/*`)

Each third-party integration resides in its own folder under `packages/`, following a **strict scaffold pattern**. With roughly 70 plugins (e.g., `packages/alchemy`, `packages/slack`), this structure ensures consistency across all integrations.

### Standard Plugin Layout

Every plugin package follows this directory structure:

```

packages/<plugin>/
├─ index.ts               # Public re-exports (client, schema, endpoints)

├─ schema/                # Type-safe API description

│   ├─ index.ts
│   └─ database.ts
├─ endpoints/             # Concrete API call implementations

│   └─ *.ts
├─ webhooks/              # Optional webhook handling utilities

├─ error-handlers.ts      # Centralized error mapping

└─ tests/                 # Plugin-specific test suite

```

### Example: The Alchemy Plugin

The Alchemy blockchain plugin demonstrates this structure in practice. Its entry point at [`packages/alchemy/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/alchemy/index.ts) cleanly exports the public surface:

```ts
// packages/alchemy/index.ts
export * from './client';
export * from './schema';

```

Concrete endpoints define type-safe parameters:

```ts
// packages/alchemy/endpoints/types.ts
export interface GetTransactionParams {
  hash: string;
}

```

## Explorer: Local Plugin Development UI (`explorer/`)

The **Explorer** is a lightweight developer tool for browsing, inspecting, and testing plugins without writing code. It runs locally and serves two key functions:

- **[`explorer/src/server.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/server.ts)** – HTTP server exposing `/catalog` endpoint and UI routes
- **[`explorer/src/catalog.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/catalog.ts)** – Walks all installed plugins, aggregates schemas, and builds a JSON catalog consumed by the UI

Start the Explorer locally with:

```bash
pnpm run explorer   # Available at http://localhost:3000

```

## Automation Scripts (`scripts/`)

TypeScript scripts in `scripts/` enforce consistency and accelerate development:

| Script | File | Purpose |
|--------|------|---------|
| **Plugin Generation** | [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) | Scaffolds new plugin packages with required structure |
| **Plugin Validation** | [`scripts/validate-plugins.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/validate-plugins.ts) | Runs structural checks across all `packages/*` directories |
| **PR Review Helpers** | `scripts/pr-review/*.ts` | Static analysis for incoming pull requests |

Generate a new plugin using:

```bash
pnpm run generate:plugin myservice

```

This creates the complete `packages/myservice/` folder with all required files.

## Testing Infrastructure (`test/` & `packages/**/tests/`)

Corsair maintains comprehensive test coverage through multiple suites:

- **`packages/corsair/tests/*.test.ts`** – Core engine tests (OAuth flows, tenant linking)
- **`packages/<plugin>/tests/*.test.ts`** – Plugin-specific behavior validation
- **Top-level `test/`** – Integration and end-to-end scenarios

Execute all tests via:

```bash
pnpm test

```

## Public Website and Documentation (`www/`)

The `www/` directory contains:

- **`corsair.dev` public site** – Marketing and documentation pages
- **`www/src/app/oss/`** – Open-source contributor dashboard with its own README at [`www/src/app/oss/README.md`](https://github.com/corsairdev/corsair/blob/main/www/src/app/oss/README.md)

## Summary

- **Core engine** (`packages/corsair/`) provides universal runtime, provider registry, and OAuth infrastructure
- **Plugin packages** (`packages/*`) isolate ~70 third-party integrations behind a uniform scaffold
- **Explorer** (`explorer/`) enables local plugin testing through a dedicated UI server
- **Scripts** (`scripts/`) automate plugin generation, validation, and PR review
- **Tests** span core, plugins, and Explorer for comprehensive coverage
- **Website** (`www/`) combines public marketing with OSS contributor tools

## Frequently Asked Questions

### Where is the complete list of supported providers in Corsair?

The authoritative list lives in [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts). This file exports `BaseProviders`, a typed array containing all ~70 supported integration keys from `'ably'` to `'zoominfo'`. It also provides `formatProviderDisplayName()` for human-readable names.

### How do I add a new plugin to Corsair?

Run `pnpm run generate:plugin <name>` to execute [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts). This scaffolds the complete directory structure including [`index.ts`](https://github.com/corsairdev/corsair/blob/main/index.ts), `schema/`, `endpoints/`, `webhooks/`, [`error-handlers.ts`](https://github.com/corsairdev/corsair/blob/main/error-handlers.ts), and `tests/` directories. The new plugin automatically follows Corsair's structural conventions.

### What is the Explorer and how do I use it?

The Explorer is a local development UI defined in [`explorer/src/server.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/server.ts) and [`explorer/src/catalog.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/catalog.ts). Start it with `pnpm run explorer`, then browse to `http://localhost:3000` to inspect plugin schemas and test endpoints without writing integration code.

### How does Corsair maintain consistency across 70+ plugins?

[`scripts/validate-plugins.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/validate-plugins.ts) enforces structural requirements on every package in `packages/*`, checking for required files and export patterns. This CI-level validation ensures all plugins conform to the scaffold defined in the core constants and generation templates.