MockServer Documentation

June 24, 2026 · View on GitHub

Comprehensive internal documentation for the MockServer project covering code architecture, infrastructure, build system, CI/CD, and deployment.

Documentation style. These docs follow the Pyramid Principle with progressive disclosure — lead with the outcome, then layer detail beneath it. The Level column below (High / Medium / Low) is that principle applied across the doc set: start High for the big picture, drill into Low for subsystem detail. See .opencode/rules/documentation-style.md for the authoring skeleton.

Documentation Index

Code Architecture

Deep-dive documentation of MockServer's codebase, from high-level module structure down to individual subsystems.

DocumentLevelDescription
Code OverviewHighModule hierarchy, dependency graph, package layout
Netty PipelineMediumPort unification, protocol detection, channel handlers, MCP handler, relay pattern
Request ProcessingMediumMock matching, proxy forwarding, action dispatch, WAR bridge
Event SystemMediumLMAX Disruptor ring buffer, verification, persistence, observers
Dashboard UIMediumReact SPA, Zustand state, twelve top-level views (Dashboard / Traffic / Sessions / Mocks / Library / Chaos / Drift / Verification / AsyncAPI / Metrics / Breakpoints / Get Started), WebSocket communication, data assembly
Domain ModelLowModel hierarchy, matchers, codecs, OpenAPI support, configuration (incl. MCP)
TLS & SecurityLowBouncyCastle CA, SNI, mTLS, JWT auth, control plane security
Client & IntegrationsLowMockServerClient, JUnit 4/5, Spring, WebSocket callbacks, VS Code extension, JetBrains plugin
Editor ExtensionsLowVS Code and JetBrains extensions: shared JSON Schema generation, REST client architecture, feature inventory, build/CI, gotchas
Memory ManagementMediumLog entry and expectation memory analysis, default limit calculation, tuning guide
Metrics & MonitoringLowPrometheus metrics, memory monitoring, CSV export
TelemetryLowOpenTelemetry integration: OTLP export, GenAI spans, W3C trace context propagation
AI & RPC Protocol MockingMediumSSE streaming, JSON-RPC matching, MCP and A2A mock builders, gRPC mocking
LLM MockingMediumLLM response builder, provider codecs, streaming physics, conversation matchers, isolation, MCP tools, dashboard
LLM Codec Golden FilesLowAutomated wire-format drift detection for the LLM provider codecs: golden-master fixtures, normalization, refresh process
CLILowpicocli command tree, subcommands, preprocessArguments heuristic, legacy flag compatibility, how to add a subcommand
Configuration ReferenceLowProperty mechanism, resolution order, four equivalent forms, how to add a property
Chaos ExperimentsLowScheduled multi-stage chaos experiments: ChaosExperimentOrchestrator, ordered stages, auto-halt integration, PUT/GET/DELETE /chaosExperiment
BreakpointsLowRequest/response/stream breakpoints: BreakpointRegistry, PausedExchange, request and response phases, stream frame interception
Drift DetectionLowMock drift detection: comparing forwarded responses against stub expectations
SLO VerdictsLowSynchronous SLO verdicts over forwarded traffic: SloSampleStore, SloEvaluator, PUT /mockserver/verifySLO (200 PASS / 406 FAIL)
Load GenerationLowAPI-driven load scenarios: LoadScenarioOrchestrator, ramp profiles, per-iteration templating, PUT/GET/DELETE /mockserver/loadScenario, SLI producer for SLO verdicts
WASM RulesLowWASM custom rule engine: chicory interpreter, module ABI, REST endpoints, configuration
Async MessagingLowAsyncAPI broker mocking: spec parsing, example generation, Kafka/MQTT publisher adapters, orchestrator
HTTP/3 (QUIC)LowExperimental HTTP/3 support: Http3Server, QUIC native dependency, MVP boundaries
Clustered StateLowStateBackend SPI, InMemoryStateBackend, InfinispanStateBackend (LOCAL/CLUSTERED), cross-node invalidation, config knobs, limitations
LLM Security AuditLowM5 security review: known codec limitations, Bedrock SigV4, Ollama NDJSON, adversarial-response safety

Infrastructure

AWS accounts, CI/CD pipelines, container images, and Kubernetes deployment.

DocumentDescription
AWS InfrastructureAWS accounts, Terraform IaC, EC2 agents, S3 hosting, CloudFront CDN
CI/CDBuildkite pipelines and GitHub Actions workflows
DockerDocker images, variants, multi-arch builds, and Compose examples
Helm & KubernetesHelm charts, deployment templates, and Kind-based testing
Service Mesh / SidecarTransparent HTTP interception and Kubernetes sidecar deployment
AWS SES Email ForwardingSES catch-all email forwarding for mock-server.com

Operations

Build process, releases, dependencies, security scanning, and the documentation website.

DocumentDescription
Build SystemMaven configuration, profiles, plugins, and build scripts
Release ProcessEnd-to-end release workflow with Mermaid diagrams
SecurityConsolidated security overview: CodeQL, Dependabot, Snyk, AI security review, SNAPSHOT policy
Snyk SecurityVulnerability scanning, CLI usage, javax/jakarta constraints, triage workflow
WebsiteJekyll documentation site structure and publishing
TestingTest frameworks, module inventory, architecture, configuration, coverage gaps, CI execution
Performance TuningInternal companion to the website performance page: where the budget goes, rules of thumb, JVM flags, measuring, regression triage
AI-Native SDLC PrinciplesPrinciples for working with AI across the SDLC: spec-first, verification, context, guardrails, the lethal trifecta
AI-Assisted DevelopmentAI development approach, adversarial review, testing backstop, structural safety
OpenCode ConfigurationAI harness: config, agents, rules, skills, commands, plugins
OpenCode Building BlocksGeneric guide to the 9 building blocks: what each controls, when to use which, and how they fit together
MCP Registry PublishingPublishing MockServer's MCP server to public MCP registries
Migration: Java 17 + JakartaCompleted javax→jakarta namespace migration: scope, approach, and verification
Release PrinciplesPrinciples and rules governing the release scripts and Buildkite release pipeline

Plans

DocumentDescription
Security DefaultsInsecure default flips planned for the next major release

Other

DocumentDescription
ArchitectureOriginal high-level architecture overview (see also Code Overview)

Quick Reference

mockserver-monorepo/
├── mockserver/                     # Java server (multi-module Maven project)
│   ├── mockserver-core/            # Core domain model, matching, serialisation
│   ├── mockserver-client-java/     # Java client library
│   ├── mockserver-netty/           # Netty-based HTTP server (main artifact)
│   ├── mockserver-war/             # WAR-packaged mock server
│   ├── mockserver-proxy-war/       # WAR-packaged proxy
│   ├── mockserver-junit-rule/      # JUnit 4 integration
│   ├── mockserver-junit-jupiter/   # JUnit 5 integration
│   ├── mockserver-spring-test-listener/ # Spring test integration
│   ├── mockserver-testing/         # Shared test utilities
│   └── mockserver-integration-testing/ # Integration test infrastructure
├── examples/                       # Runnable usage examples (java/node/python/ruby/curl/json/docker-compose/wasm/chaos)
├── mockserver-ui/                  # React dashboard UI (Vite + TypeScript)
├── mockserver-node/                # Node.js MockServer launcher (npm)
├── mockserver-client-node/         # Node.js/browser client library (npm)
├── mockserver-client-python/       # Python client library (PyPI)
├── mockserver-client-ruby/         # Ruby client library (RubyGems)
├── mockserver-performance-test/    # k6-based performance tests
├── container_integration_tests/    # Docker & Helm integration tests
├── jekyll-www.mock-server.com/     # Jekyll documentation website
├── helm/                           # Helm charts (mockserver + mockserver-config)
├── docker/                         # Production Docker images (5 variants)
├── docker_build/                   # CI build Docker images
├── terraform/                      # Terraform IaC (Buildkite agents + pipelines)
├── scripts/                        # Build, deploy, and utility scripts
└── docs/                           # This documentation (you are here)
    ├── code/                       #   Code architecture (25 docs)
    ├── infrastructure/             #   AWS, CI/CD, Docker, Helm, Service Mesh (6 docs)
    ├── operations/                 #   Build, release, deps, security, website, perf (15 docs)
    ├── plans/                      #   Active plans and RFCs (1 doc)
    └── testing.md                  #   Test frameworks, architecture, config, coverage, CI