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

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. This file exports BaseProviders, a constant array enumerating every provider Corsair supports:

// 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 – 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, which exposes the Corsair class used by all consumers:

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 cleanly exports the public surface:

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

Concrete endpoints define type-safe parameters:

// 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 – HTTP server exposing /catalog endpoint and UI routes
• explorer/src/catalog.ts – Walks all installed plugins, aggregates schemas, and builds a JSON catalog consumed by the UI

Start the Explorer locally with:

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	Scaffolds new plugin packages with required structure
Plugin Validation	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:

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:

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

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. 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. This scaffolds the complete directory structure including index.ts, schema/, endpoints/, webhooks/, 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 and 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 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.

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