FoundryCI

Architecture

packages/
  emulate/          # CLI entry point (commander)
  @emulators/
    core/           # HTTP server, in-memory store, plugin interface, middleware
    adapter-next/   # Next.js App Router 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
    apple/          # Apple Sign In / OIDC
    microsoft/      # Microsoft Entra ID OAuth 2.0 / OIDC + Graph /me
    clerk/          # Clerk users + organizations + OAuth applications
    foundry/        # Foundry OAuth 2.0 + compute modules + current user
    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
apps/
  web-svelte/       # Deployable docs site (SvelteKit + Cloudflare adapter)
  web/              # Upstream Next.js docs / content source (not deployed)

Core

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

Plugin System

Each service is a plugin that:

  1. Defines its entity types and store collections
  2. Registers HTTP routes on the shared Hono 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