---
title: "Architecture"
description: "Local drop-in replacement services for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation."
canonical_url: "https://emulate.dev/docs/architecture"
---
# Architecture

```
packages/
  emulate/          # CLI entry point (commander)
  @emulators/
    core/           # HTTP server, in-memory store, plugin interface, middleware
    adapter-next/   # Next.js App Router integration
    adapter-nuxt/   # Nuxt server route integration
    vercel/         # Vercel API service
    github/         # GitHub API service
    google/         # Google OAuth 2.0 / OIDC + Gmail, Calendar, Drive
    slack/          # Slack Web API, OAuth v2, incoming webhooks
    linear/         # Linear GraphQL API, OAuth, webhooks
    twilio/         # Twilio Messaging, Verify, Voice, webhooks
    apple/          # Apple Sign In / OIDC
    microsoft/      # Microsoft Entra ID OAuth 2.0 / OIDC + Graph /me
    aws/            # AWS S3, SQS, IAM, STS
    okta/           # Okta identity provider / OIDC
    mongoatlas/     # MongoDB Atlas Admin API + Data API
    resend/         # Resend email API
    stripe/         # Stripe billing and payments API
    clerk/          # Clerk Backend API and OAuth
apps/
  web/              # Documentation site (Next.js)
```

## 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/vercel-labs/emulate/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).

## 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.

## 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, Vercel-style cursor-based pagination

## Custom emulators

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