# counterfact/api-simulator architecture

> Architecture diagram of the GitHub repository counterfact/api-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/counterfact/api-simulator
- Repository: https://github.com/counterfact/api-simulator

## Overview

Counterfact is an OpenAPI-driven mock API server: developers provide a contract, generate editable route scaffolding and types, then send client requests to a local API that simulates responses or selectively proxies them. The CLI and application coordinate setup; runtime middleware routes requests into dispatch and can forward selected paths. The repository also includes a typed client and interactive REPL. The graph follows README-described capabilities and sampled/indexed imports; several runtime internals are unsampled, so their relationships are omitted rather than inferred.

Main entry points: [`packages/counterfact/src/app.ts`](https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/app.ts) (Application setup), [`packages/openapi/src/load-openapi-document.ts`](https://github.com/counterfact/api-simulator/blob/main/packages/openapi/src/load-openapi-document.ts) (OpenAPI loading), [`packages/runtime/src/server/web-server/routes-middleware.ts`](https://github.com/counterfact/api-simulator/blob/main/packages/runtime/src/server/web-server/routes-middleware.ts) (HTTP middleware), [`packages/counterfact/src/cli/run.ts`](https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/cli/run.ts) (Counterfact CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and application"]
  node_cli["Counterfact CLI<br/>[run.ts]"]
  node_app["Application setup<br/>[app.ts]"]
  node_api_runner["API runner<br/>[api-runner.ts]"]
end

subgraph group_contract["Contract and generation"]
  node_openapi["OpenAPI loading"]
  node_generator_repo["Generated repository<br/>[repository.ts]"]
  node_scenario_generator["Scenario scaffolding"]
  node_generated_routes["Editable routes<br/>[repository.ts]"]
  node_generated_types["Generated types"]
  node_typed_responses["Response types"]
end

subgraph group_runtime["API runtime"]
  node_web_server["HTTP middleware"]
  node_dispatcher["Request dispatcher<br/>[dispatcher.ts]"]
end

subgraph group_developer["Developer tools"]
  node_repl["Interactive REPL<br/>[repl.ts]"]
  node_client_routes["Typed route client<br/>[route-builder.ts]"]
  node_raw_client["HTTP client<br/>[raw-http-client.ts]"]
end

node_developer_actor(("API developer"))
node_api_consumers(("Frontend clients"))
node_proxy{{"Real API service"}}

node_developer_actor -->|"starts"| node_cli
node_cli -->|"loads contract"| node_openapi
node_cli -->|"starts application"| node_app
node_app -->|"configures APIs"| node_api_runner
node_app -->|"creates generated files"| node_generator_repo
node_app -->|"generates scenarios"| node_scenario_generator
node_generator_repo -->|"writes routes"| node_generated_routes
node_generator_repo -->|"writes types"| node_generated_types
node_developer_actor -->|"provides contract"| node_openapi
node_openapi -->|"defines interface"| node_generated_routes
node_openapi -->|"drives type generation"| node_generated_types
node_api_consumers -->|"sends requests"| node_web_server
node_app -->|"starts local API"| node_web_server
node_web_server -->|"dispatches requests"| node_dispatcher
node_web_server -->|"forwards selected paths"| node_proxy
node_app -->|"launches REPL"| node_repl
node_app -->|"provides route client"| node_client_routes
node_client_routes -->|"sends HTTP"| node_raw_client
node_repl -->|"uses typed routes"| node_client_routes
node_generated_routes -.->|"enables typed responses"| node_typed_responses

click node_cli "https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/cli/run.ts"
click node_app "https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/app.ts"
click node_api_runner "https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/api-runner.ts"
click node_openapi "https://github.com/counterfact/api-simulator/blob/main/packages/openapi/src/load-openapi-document.ts"
click node_generator_repo "https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/repository.ts"
click node_scenario_generator "https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/scenario-file-generator.ts"
click node_generated_routes "https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/repository.ts"
click node_generated_types "https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/operation-type-coder.ts"
click node_typed_responses "https://github.com/counterfact/api-simulator/blob/main/packages/types/src/generic-response-builder.ts"
click node_web_server "https://github.com/counterfact/api-simulator/blob/main/packages/runtime/src/server/web-server/routes-middleware.ts"
click node_dispatcher "https://github.com/counterfact/api-simulator/blob/main/packages/runtime/src/server/dispatcher.ts"
click node_repl "https://github.com/counterfact/api-simulator/blob/main/packages/repl/src/repl.ts"
click node_client_routes "https://github.com/counterfact/api-simulator/blob/main/packages/client/src/route-builder.ts"
click node_raw_client "https://github.com/counterfact/api-simulator/blob/main/packages/client/src/raw-http-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_app,node_api_runner,node_api_consumers toneBlue
class node_openapi,node_generator_repo,node_scenario_generator,node_generated_routes,node_generated_types,node_typed_responses toneAmber
class node_web_server,node_dispatcher,node_developer_actor,node_proxy toneMint
class node_repl,node_client_routes,node_raw_client toneRose
```

## Components

### CLI and application

- [Counterfact CLI](https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/cli/run.ts): `packages/counterfact/src/cli/run.ts`
- [Application setup](https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/app.ts): `packages/counterfact/src/app.ts`
- [API runner](https://github.com/counterfact/api-simulator/blob/main/packages/counterfact/src/api-runner.ts): `packages/counterfact/src/api-runner.ts`

### Contract and generation

- [OpenAPI loading](https://github.com/counterfact/api-simulator/blob/main/packages/openapi/src/load-openapi-document.ts): `packages/openapi/src/load-openapi-document.ts`
- [Generated repository](https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/repository.ts): `packages/generator/src/repository.ts`
- [Scenario scaffolding](https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/scenario-file-generator.ts): `packages/generator/src/scenario-file-generator.ts`
- [Editable routes](https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/repository.ts): `packages/generator/src/repository.ts`
- [Generated types](https://github.com/counterfact/api-simulator/blob/main/packages/generator/src/operation-type-coder.ts): `packages/generator/src/operation-type-coder.ts`
- [Response types](https://github.com/counterfact/api-simulator/blob/main/packages/types/src/generic-response-builder.ts): `packages/types/src/generic-response-builder.ts`

### API runtime

- [HTTP middleware](https://github.com/counterfact/api-simulator/blob/main/packages/runtime/src/server/web-server/routes-middleware.ts): `packages/runtime/src/server/web-server/routes-middleware.ts`
- [Request dispatcher](https://github.com/counterfact/api-simulator/blob/main/packages/runtime/src/server/dispatcher.ts): `packages/runtime/src/server/dispatcher.ts`

### Developer tools

- [Interactive REPL](https://github.com/counterfact/api-simulator/blob/main/packages/repl/src/repl.ts): `packages/repl/src/repl.ts`
- [Typed route client](https://github.com/counterfact/api-simulator/blob/main/packages/client/src/route-builder.ts): `packages/client/src/route-builder.ts`
- [HTTP client](https://github.com/counterfact/api-simulator/blob/main/packages/client/src/raw-http-client.ts): `packages/client/src/raw-http-client.ts`

### Other components

- **API developer**
- **Frontend clients**
- **Real API service**

## Connections

- API developer → Counterfact CLI: starts (evidence: `README.md`)
- Counterfact CLI → OpenAPI loading: loads contract
- Counterfact CLI → Application setup: starts application (evidence: `packages/counterfact/src/cli/run.ts`)
- Application setup → API runner: configures APIs (evidence: `packages/counterfact/src/app.ts`)
- Application setup → Generated repository: creates generated files (evidence: `packages/counterfact/src/app.ts`)
- Application setup → Scenario scaffolding: generates scenarios (evidence: `packages/counterfact/src/app.ts`)
- Generated repository → Editable routes: writes routes (evidence: `packages/generator/src/repository.ts`)
- Generated repository → Generated types: writes types (evidence: `packages/generator/src/repository.ts`)
- API developer → OpenAPI loading: provides contract (evidence: `README.md`)
- OpenAPI loading → Editable routes: defines interface (evidence: `README.md`)
- OpenAPI loading → Generated types: drives type generation (evidence: `README.md`)
- Frontend clients → HTTP middleware: sends requests (evidence: `README.md`)
- Application setup → HTTP middleware: starts local API (evidence: `packages/counterfact/src/app.ts`)
- HTTP middleware → Request dispatcher: dispatches requests (evidence: `packages/runtime/src/server/web-server/routes-middleware.ts`)
- HTTP middleware → Real API service: forwards selected paths (evidence: `packages/runtime/src/server/web-server/routes-middleware.ts`)
- Application setup → Interactive REPL: launches REPL (evidence: `packages/counterfact/src/app.ts`)
- Application setup → Typed route client: provides route client (evidence: `packages/counterfact/src/app.ts`)
- Typed route client → HTTP client: sends HTTP (evidence: `packages/client/src/route-builder.ts`)
- Interactive REPL → Typed route client: uses typed routes (evidence: `packages/repl/src/repl.ts`)
- Editable routes → Response types: enables typed responses