# mockctl-hq/mockctl architecture

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

- Interactive diagram: https://gitdiagram.com/mockctl-hq/mockctl
- Repository: https://github.com/mockctl-hq/mockctl

## Overview

Mock:ctl is an API simulation engine with a terminal-based Studio and an HTTP runtime. The main workflow is to load an OpenAPI specification, compile route and response templates (including generated schema data and workspace overrides), then serve mock endpoints to API clients; the Studio supports project editing, API testing, and runtime inspection. The graph includes documented/runtime subsystems visible in the tree, but source excerpts are incomplete, so uncertain connections—especially among individual admin and Studio tools—are left out.

Main entry points: [`internal/tui/app.go`](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/app.go) (Studio app), [`internal/app/app.go`](https://github.com/mockctl-hq/mockctl/blob/main/internal/app/app.go) (Application core), [`internal/app/project_manager.go`](https://github.com/mockctl-hq/mockctl/blob/main/internal/app/project_manager.go) (Project manager), [`internal/runtime/server.go`](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/server.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project authoring"]
  node_app["Application core<br/>[app.go]"]
  node_project_manager["Project manager<br/>[project_manager.go]"]
  node_openapi_parser["OpenAPI parser<br/>[parser.go]"]
  node_mock_generator["Mock generator<br/>[generator.go]"]
  node_payload_builder["Payload builder<br/>[builder.go]"]
end

subgraph group_runtime["Mock API runtime"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_gateway["Project gateway<br/>[gateway.go]"]
  node_runtime_engine["Runtime engine<br/>[engine.go]"]
  node_request_handlers["Request handlers<br/>[handlers.go]"]
  node_admin_routes["Admin routes<br/>[admin_routes.go]"]
end

subgraph group_state["State and telemetry"]
  node_event_broker["Event broker<br/>[broker.go]"]
  node_state_store[("Mock state<br/>[memory_state.go]")]
  node_system_store[("System database<br/>[bbolt_system.go]")]
  node_telemetry_persister["Telemetry persister"]
end

subgraph group_studio["Terminal Studio"]
  node_studio_root["Studio app<br/>[app.go]"]
  node_workspace["Workspace editor<br/>[workspace.go]"]
  node_http_tester["HTTP tester<br/>[client.go]"]
  node_project_explorer["Project explorer<br/>[explorer.go]"]
  node_runtime_controls["Runtime controls<br/>[chaos.go]"]
  node_history["Request history<br/>[history.go]"]
  node_studio_tools["Studio tools<br/>[settings.go]"]
end

node_developer(("Developer"))
node_api_client(("API client"))

node_developer -->|"uses"| node_studio_root
node_api_client -->|"sends requests"| node_http_server
node_studio_root -->|"initializes"| node_workspace
node_studio_root -->|"initializes"| node_project_explorer
node_studio_root -->|"initializes"| node_history
node_studio_root -->|"initializes"| node_studio_tools
node_workspace -.->|"contains"| node_http_tester
node_project_manager -->|"parses spec"| node_openapi_parser
node_project_manager -->|"compiles engine"| node_mock_generator
node_mock_generator -->|"builds payloads"| node_payload_builder
node_app -.->|"coordinates"| node_project_manager
node_app -->|"persists settings"| node_system_store
node_app -->|"starts"| node_http_server
node_http_server -->|"mounts"| node_admin_routes
node_http_server -->|"mounts catch-all"| node_runtime_engine
node_runtime_engine -->|"dispatches methods"| node_request_handlers
node_request_handlers -->|"reads and writes"| node_state_store
node_app -.->|"publishes runtime events"| node_event_broker
node_app -->|"starts"| node_telemetry_persister
node_telemetry_persister -.->|"persists telemetry"| node_system_store
node_studio_root -->|"subscribes telemetry"| node_event_broker
node_history -.->|"queries runtime"| node_runtime_engine
node_runtime_controls -.->|"configures behavior"| node_runtime_engine
node_project_manager -.->|"loads and saves projects"| node_system_store

click node_app "https://github.com/mockctl-hq/mockctl/blob/main/internal/app/app.go"
click node_project_manager "https://github.com/mockctl-hq/mockctl/blob/main/internal/app/project_manager.go"
click node_openapi_parser "https://github.com/mockctl-hq/mockctl/blob/main/internal/spec/parser.go"
click node_mock_generator "https://github.com/mockctl-hq/mockctl/blob/main/internal/generator/generator.go"
click node_payload_builder "https://github.com/mockctl-hq/mockctl/blob/main/internal/data/builder.go"
click node_http_server "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/server.go"
click node_gateway "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/gateway.go"
click node_runtime_engine "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/engine.go"
click node_request_handlers "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/handlers.go"
click node_admin_routes "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/admin_routes.go"
click node_event_broker "https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/broker.go"
click node_state_store "https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/memory_state.go"
click node_system_store "https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/bbolt_system.go"
click node_telemetry_persister "https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/telemetry_persister.go"
click node_studio_root "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/app.go"
click node_workspace "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/workspace/workspace.go"
click node_http_tester "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/workspace/tester/protocols/http/client.go"
click node_project_explorer "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/sidebars/left/inner/body/explorer.go"
click node_runtime_controls "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/sidebars/right/inner/body/chaos.go"
click node_history "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/overlays/header_tools/history/history.go"
click node_studio_tools "https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/overlays/header_tools/settings/settings.go"

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_app,node_project_manager,node_openapi_parser,node_mock_generator,node_payload_builder,node_api_client toneBlue
class node_http_server,node_gateway,node_runtime_engine,node_request_handlers,node_admin_routes toneAmber
class node_event_broker,node_state_store,node_system_store,node_telemetry_persister toneMint
class node_studio_root,node_workspace,node_http_tester,node_project_explorer,node_runtime_controls,node_history,node_studio_tools toneRose
class node_developer toneIndigo
```

## Components

### Project authoring

- [Application core](https://github.com/mockctl-hq/mockctl/blob/main/internal/app/app.go): `internal/app/app.go`
- [Project manager](https://github.com/mockctl-hq/mockctl/blob/main/internal/app/project_manager.go): `internal/app/project_manager.go`
- [OpenAPI parser](https://github.com/mockctl-hq/mockctl/blob/main/internal/spec/parser.go): `internal/spec/parser.go`
- [Mock generator](https://github.com/mockctl-hq/mockctl/blob/main/internal/generator/generator.go): `internal/generator/generator.go`
- [Payload builder](https://github.com/mockctl-hq/mockctl/blob/main/internal/data/builder.go): `internal/data/builder.go`

### Mock API runtime

- [HTTP server](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/server.go): `internal/runtime/server.go`
- [Project gateway](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/gateway.go): `internal/runtime/gateway.go`
- [Runtime engine](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/engine.go): `internal/runtime/engine.go`
- [Request handlers](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/handlers.go): `internal/runtime/handlers.go`
- [Admin routes](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/admin_routes.go): `internal/runtime/admin_routes.go`

### State and telemetry

- [Event broker](https://github.com/mockctl-hq/mockctl/blob/main/internal/runtime/broker.go): `internal/runtime/broker.go`
- [Mock state](https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/memory_state.go): `internal/storage/memory_state.go`
- [System database](https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/bbolt_system.go): `internal/storage/bbolt_system.go`
- [Telemetry persister](https://github.com/mockctl-hq/mockctl/blob/main/internal/storage/telemetry_persister.go): `internal/storage/telemetry_persister.go`

### Terminal Studio

- [Studio app](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/app.go): `internal/tui/app.go`
- [Workspace editor](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/workspace/workspace.go): `internal/tui/components/workspace/workspace.go`
- [HTTP tester](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/workspace/tester/protocols/http/client.go): `internal/tui/components/workspace/tester/protocols/http/client.go`
- [Project explorer](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/sidebars/left/inner/body/explorer.go): `internal/tui/components/sidebars/left/inner/body/explorer.go`
- [Runtime controls](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/sidebars/right/inner/body/chaos.go): `internal/tui/components/sidebars/right/inner/body/chaos.go`
- [Request history](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/overlays/header_tools/history/history.go): `internal/tui/components/overlays/header_tools/history/history.go`
- [Studio tools](https://github.com/mockctl-hq/mockctl/blob/main/internal/tui/components/overlays/header_tools/settings/settings.go): `internal/tui/components/overlays/header_tools/settings/settings.go`

### Other components

- **Developer**
- **API client**

## Connections

- Developer → Studio app: uses
- API client → HTTP server: sends requests
- Studio app → Workspace editor: initializes (evidence: `internal/tui/app.go`)
- Studio app → Project explorer: initializes (evidence: `internal/tui/app.go`)
- Studio app → Request history: initializes (evidence: `internal/tui/app.go`)
- Studio app → Studio tools: initializes (evidence: `internal/tui/app.go`)
- Workspace editor → HTTP tester: contains
- Project manager → OpenAPI parser: parses spec (evidence: `internal/app/project_manager.go`)
- Project manager → Mock generator: compiles engine (evidence: `internal/app/project_manager.go`)
- Mock generator → Payload builder: builds payloads (evidence: `internal/generator/generator.go`)
- Application core → Project manager: coordinates
- Application core → System database: persists settings (evidence: `internal/app/app.go`)
- Application core → HTTP server: starts (evidence: `internal/app/app.go`)
- HTTP server → Admin routes: mounts (evidence: `internal/runtime/server.go`)
- HTTP server → Runtime engine: mounts catch-all (evidence: `internal/runtime/server.go`)
- Runtime engine → Request handlers: dispatches methods (evidence: `internal/runtime/engine.go`)
- Request handlers → Mock state: reads and writes (evidence: `internal/runtime/handlers.go`)
- Application core → Event broker: publishes runtime events
- Application core → Telemetry persister: starts (evidence: `internal/app/app.go`)
- Telemetry persister → System database: persists telemetry
- Studio app → Event broker: subscribes telemetry (evidence: `internal/tui/app.go`)
- Request history → Runtime engine: queries runtime
- Runtime controls → Runtime engine: configures behavior
- Project manager → System database: loads and saves projects
