> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploybaseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the packages fit together: the core server and store, one plugin per provider, and shared middleware.

```
packages/
  cli/              # CLI entry point (commander)
  @deploybaseline/
    core/           # HTTP server, in-memory store, plugin interface, middleware
    graphql/        # GraphQL kit (GitHub, Linear, and Shopify run on it)
    ws/             # WebSocket kit (Slack Socket Mode and the Discord Gateway bundle it)
    testing/        # Provider test harness: startService, restartService, webhook sink
    state-sqlite/   # --state sqlite:<path>
    state-libsql/   # --state libsql://<host>
    # Identity and auth
    auth0/          # Universal Login, OAuth and OIDC, Management API, role-based access control
    clerk/          # Frontend API, Backend API, OAuth and OIDC, organizations, sessions, JWT templates
    okta/           # OAuth 2.0 and OIDC, authorization servers, users, groups, apps
    apple/          # Sign in with Apple: authorization, client secrets, ID tokens, server-to-server notifications
    # Workspace and productivity
    google/         # OAuth 2.0 and OIDC, Gmail, Calendar, Drive, Sheets, Docs
    microsoft/      # Entra ID OAuth 2.0 and OIDC, Microsoft Graph: Outlook mail, calendar, contacts, To Do, users and groups
    notion/         # Pages, databases and data sources, queries, search, blocks, comments, OAuth, webhooks
    # Messaging and email
    slack/          # Web API, OAuth v2, incoming webhooks, interactivity, events, Socket Mode
    discord/        # Bot REST API, Gateway over WebSocket, interactions, OAuth2, rate limits
    twilio/         # Programmable Messaging, Messaging Services, Verify, Voice, Conversations
    whatsapp/       # Cloud API messages, templates, media, phone numbers and accounts, webhooks
    resend/         # Emails, idempotency, domains, API keys, audiences and contacts, a local inbox
    sendgrid/       # Mail Send, scheduling, templates, API keys, Marketing, Event Webhook, a local inbox
    # Payments and commerce
    stripe/         # Customers, Payment and Setup Intents, charges, refunds, subscriptions, invoices, Checkout, Connect, webhooks
    paypal/         # Orders v2, a hosted approval page, Payments v2, webhooks
    square/         # Payments, refunds, orders, customers, catalog, locations, OAuth, webhooks
    plaid/          # Link, items and accounts, transactions, institutions, sandbox helpers, webhooks
    shopify/        # Admin GraphQL API, OAuth, webhooks
    # Developer platforms
    github/         # REST and GraphQL: repositories, issues, pull requests, organizations, webhooks, Actions, Checks, OAuth Apps and GitHub Apps
    linear/         # GraphQL API, OAuth, webhooks
    jira/           # REST API, JQL search, Agile boards and sprints, OAuth 2.0 (3LO), webhooks
    # CRM and support
    salesforce/     # Records, SOQL, describe, sObject collections, composite requests, OAuth
    hubspot/        # CRM objects, search, associations, properties, pipelines, owners, OAuth, webhooks
    zendesk/        # Tickets, comments, users, organizations and groups, search, views, triggers, OAuth, webhooks
    servicenow/     # Table API, Attachment API, Aggregate API
    # Finance and ERP
    netsuite/       # Records, transforms, SuiteQL, custom fields and records, metadata, OAuth 2.0
    quickbooks/     # Accounting entities, queries, batch, change data capture, OAuth 2.0, webhooks
    xero/           # Accounting API, OAuth 2.0 and OpenID Connect, webhooks
docs/               # Documentation site (Mintlify)
```

## Core

The core package provides a generic `Store` with typed `Collection<T>` instances supporting CRUD, indexing, filtering, and pagination. Each service plugin registers its routes with the shared internal app and uses the store for state.

The internal HTTP layer builds on [Hono](https://hono.dev)'s API and design. Thank you to Yusuke Wada and the Hono contributors. Hono's copyright and MIT license notice are included in [THIRD\_PARTY\_NOTICES.md](https://github.com/deploybaseline/cli/blob/main/THIRD_PARTY_NOTICES.md) and distributed with the npm packages.

## Plugin system

Each service is a plugin that:

1. Defines its entity types and store collections
2. Registers HTTP routes with the shared internal app
3. Provides a seed function to populate initial state from config
4. Uses shared middleware for auth, error handling, and pagination

Multiple services can run simultaneously, each on its own port (auto-incremented from the base port).

## One process per provider

The CLI and `createEmulator` run each built-in service in its own Node process. The CLI is the host: it reads the config, keeps the saved state and the control API, and starts a provider process per service. Each provider listens on its own port and answers its traffic directly, WebSockets included; the host never sits in the request path. The two talk over Node's IPC channel with a small versioned protocol: the host starts a provider with its seed and tokens, asks it for its state when it is saved, restores it, resets it, and sets its faults. A provider forwards `/_baseline/*` requests to the host, so every service port still answers the control API for the whole run.

When a provider crashes, the host restarts it on the same port from the last state it holds, up to three times a minute. Custom emulators stay in the host process.

## In-memory state

All state is held in memory with no database. This makes the emulator fast, easy to reset, and ideal for CI pipelines. State is populated from the seed config on startup and can be modified via API calls during a test run.

When state is saved ([`--state`](/state), or `createEmulator({ state })`), it is written as one JSON document, `format: 2`, with an entry per service. Each entry holds a snapshot of the service's store, its token map, and its webhook subscriptions, plus the provider's `stateVersion` and the provider package and version that wrote it. Files written as `format: 1` still load. Loading checks `stateVersion` first, so data saved for an older entity shape is refused with a message naming the service rather than loaded half broken. Snapshots written before the format existed load and are upgraded in memory.

## Middleware

The core provides shared middleware:

* **Auth**: validates Bearer/token authorization headers against configured tokens
* **Error handling**: consistent error responses matching each service's format
* **Pagination**: GitHub-style `page`/`per_page` with `Link` headers, cursor-based pagination (Slack, Notion, Stripe)

## Custom emulators

Custom definitions created with `defineEmulator` from `@deploybaseline/cli` work in the CLI and in in-process tests. The same definition provides typed state, HTTP handlers, reset, versioned snapshots, and optional inspection/persistence. See [Custom emulators](/custom-emulators.md) for the quickstart, API reference, and complete lifecycle semantics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.