--- title: Contributing description: Contribute to MockServer -- explore the codebase architecture, build from source, run tests, and understand the module structure and CI/CD pipeline. layout: page pageOrder: 11 section: 'General' subsection: true sitemap: priority: 0.6 changefreq: 'monthly' lastmod: 2026-05-04T08:00:00+01:00 ---

MockServer is an open-source project that welcomes contributions and encourages users to understand its internals.

Whether you're looking to contribute code, report issues effectively, or simply understand how MockServer works under the hood, the developer documentation on GitHub provides comprehensive technical details about the codebase, infrastructure, and operations.

## Developer Documentation on GitHub

The docs/ directory on GitHub contains detailed internal documentation organized into four main areas:

### Code Architecture

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

Document | Description
--- | ---
Code Overview | Module hierarchy, dependency graph, package layout
Netty Pipeline | Port unification, protocol detection, channel handlers, relay pattern
Request Processing | Mock matching, proxy forwarding, action dispatch, WAR bridge
Event System | LMAX Disruptor ring buffer, verification, persistence, observers
Dashboard UI | React SPA, Redux state, WebSocket communication, data assembly
Domain Model | Model hierarchy, matchers, codecs, OpenAPI support, configuration
TLS & Security | BouncyCastle CA, SNI, mTLS, JWT auth, control plane security
Client & Integrations | MockServerClient, JUnit 4/5, Spring, WebSocket callbacks
Memory Management | Log entry and expectation memory analysis, default limit calculation, tuning guide
Metrics & Monitoring | Prometheus metrics, memory monitoring, CSV export

### Infrastructure

Documentation covering AWS accounts, CI/CD pipelines, container images, and Kubernetes deployment:

Document | Description
--- | ---
AWS Infrastructure | AWS accounts, Terraform IaC, EC2 agents, S3 hosting, CloudFront CDN
CI/CD | Buildkite pipelines and GitHub Actions workflows
Docker | Docker images, variants, multi-arch builds, and Compose examples
Helm & Kubernetes | Helm charts, deployment templates, and Kind-based testing

### Operations

Documentation about the build process, releases, dependencies, and the documentation website:

Document | Description
--- | ---
Build System | Maven configuration, profiles, plugins, and build scripts
Release Process | End-to-end release workflow with diagrams
Security & Dependencies | Java 11 compatibility policy, dependency version ceilings, and security scanning
Website | Jekyll documentation site structure and publishing
Testing | Test frameworks, module inventory, architecture, configuration, coverage gaps, CI execution

### Additional Resources

Document | Description
--- | ---
Architecture | High-level architecture overview
Gaps & Recommendations | Review of missing documentation and improvement areas

## Contributing Code

If you're interested in contributing to MockServer:

1. Start with the documentation — Read the documentation index to understand the codebase structure
2. Review the architecture — Understand the module hierarchy and dependencies in the Code Overview
3. Check the issue tracker — Browse open issues for good first contributions
4. Follow conventions — Match the existing code style, test patterns, and commit message format used in the project
5. Submit a pull request — Include tests and ensure all CI checks pass

## Reporting Issues

To report bugs or request features:

1. Check existing issues — Search the issue tracker to avoid duplicates
2. Provide details — Include MockServer version, configuration, minimal reproduction steps, and expected vs actual behavior
3. Enable debug logging — Use the debugging features to gather diagnostic information
4. Submit on GitHub — Create a new issue with all the relevant details

## Community

- GitHub — Source code and issue tracker
- Project Roadmap — GitHub Project board
- Examples — Code examples on GitHub