Multiplayer Matchmaker Service

A distributed, event-driven matchmaking platform built with Spring Boot, Spring Modulith, and Kafka.

Architecture

This project implements Domain-Driven Design with four bounded contexts:

Player Context: Player profiles, MMR, and status management
Matchmaking Context: Queue management and matchmaking policies
Match Lifecycle Context: Match states and results
Game Events Context: Real-time event processing and validation

Technology Stack

Java 25 with Spring Boot 4.0.1
Spring Modulith 2.0.0 for modular monolith architecture
Spock Framework for BDD-style testing
Apache Kafka for event-driven communication
Testcontainers for integration testing
GitLab CI/CD following DORA best practices

Development Setup

Prerequisites

Java 25 (JDK)
Docker and Docker Compose
Gradle (wrapper included)

Build Commands

# Build the project
./gradlew build

# Run the application
./gradlew bootRun

# Run unit tests (fast)
./gradlew test

# Run integration tests (with Testcontainers)
./gradlew integrationTest

# Run all tests
./gradlew check

# Clean build artifacts
./gradlew clean

Running Locally

Start local infrastructure (Kafka, etc.):

docker compose up -d

Run the application:

./gradlew bootRun

Access health check:

curl http://localhost:8080/actuator/health

Testing Approach

We follow Test-Driven Development (TDD) with Spock Framework for BDD-style tests.

Test Structure

All tests use given-when-then narratives:

def "player with MMR 1500 should match with players between 1400-1600"() {
    given: "a player with MMR 1500 enters the queue"
    def player = new Player(mmr: 1500)

    when: "matchmaking runs"
    def matches = matchmaker.findMatches()

    then: "player is matched with compatible player"
    matches[0].players.contains(player)
}

Test Categories

Unit Tests:
```
src/test/groovy
```
- Fast, isolated tests with mocked dependencies
Integration Tests:
```
src/integrationTest/groovy
```
- Full Spring context with Testcontainers

CI/CD Pipeline

Our GitLab CI/CD pipeline follows DORA best practices with these stages:

Build - Compile the application
Test - Run unit and integration tests in parallel
Quality - Static analysis and code quality checks
Package - Build Docker image
Deploy - Deploy to environments (dev, staging, production)
Verify - Smoke tests after deployment

DORA Metrics Targets

Deployment Frequency: Multiple times per day
Lead Time: Commit to production < 1 hour
MTTR: Mean time to recovery < 1 hour
Change Failure Rate: < 15%

Development Workflow

We follow Kent Beck's TDD + Tidy First approach:

Red: Write a failing test
Green: Write minimum code to pass the test
Refactor: Improve structure (only when tests are green)
Commit: Separate commits for structural vs behavioral changes

Commit Discipline

✅ Commit only when ALL tests pass
✅ No compiler/linter warnings
✅ Single logical unit of work
✅ Clear message indicating structural or behavioral change

Examples:

refactor: extract matchmaking policy to separate class

```
feat: add MMR-based matchmaking
```

Design Principles

CUPID over SOLID (Dan North): Composable, Unix philosophy, Predictable, Idiomatic, Domain-based
Effective Java (Josh Bloch): Immutability, static factories, defensive copies, builders
DDD Patterns: Aggregates, entities, value objects, domain events
Event-Driven: Loose coupling via domain events and Kafka

Project Structure

src/
├── main/
│   ├── java/                    # Production code (Java)
│   │   └── org/robbiemcarthur/multiplayermatchmakerservice/
│   │       ├── player/          # Player bounded context
│   │       ├── matchmaking/     # Matchmaking bounded context
│   │       ├── match/           # Match lifecycle bounded context
│   │       └── gameevents/      # Game events bounded context
│   └── resources/
│       └── application.yml      # Application configuration
├── test/
│   └── groovy/                  # Unit tests (Spock)
└── integrationTest/
    └── groovy/                  # Integration tests (Spock + Testcontainers)

Configuration

Main configuration:

src/main/resources/application.yml

Profile-specific configs:

```
application-dev.yml
```
- Local development
```
application-test.yml
```
- Test environment
```
application-prod.yml
```
- Production

Docker

Build Docker image:

docker build -t multiplayer-matchmaker-service .

Run container:

docker run -p 8080:8080 multiplayer-matchmaker-service

Repository

GitLab (primary): https://gitlab.com/robbiemcarthur/multiplayer-matchmaking-service
CI/CD: GitLab CI/CD with automated testing and deployment

Contributing

Please read CLAUDE.md for development guidelines and architectural decisions.

See GIT_WORKFLOW.md for TDD commit workflow.

License

[Add your license here]

Multiplayer Matchmaker Service

A distributed, event-driven matchmaking platform built with Spring Boot, Spring Modulith, and Kafka.

Architecture

This project implements Domain-Driven Design with four bounded contexts:

Player Context: Player profiles, MMR, and status management
Matchmaking Context: Queue management and matchmaking policies
Match Lifecycle Context: Match states and results
Game Events Context: Real-time event processing and validation

Technology Stack

Java 25 with Spring Boot 4.0.1
Spring Modulith 2.0.0 for modular monolith architecture
Spock Framework for BDD-style testing
Apache Kafka for event-driven communication
Testcontainers for integration testing
GitLab CI/CD following DORA best practices

Development Setup

Prerequisites

Java 25 (JDK)
Docker and Docker Compose
Gradle (wrapper included)

Build Commands

# Build the project
./gradlew build

# Run the application
./gradlew bootRun

# Run unit tests (fast)
./gradlew test

# Run integration tests (with Testcontainers)
./gradlew integrationTest

# Run all tests
./gradlew check

# Clean build artifacts
./gradlew clean

Running Locally

Start local infrastructure (Kafka, etc.):

docker compose up -d

Run the application:

./gradlew bootRun

Access health check:

curl http://localhost:8080/actuator/health

Testing Approach

We follow Test-Driven Development (TDD) with Spock Framework for BDD-style tests.

Test Structure

All tests use given-when-then narratives:

def "player with MMR 1500 should match with players between 1400-1600"() {
    given: "a player with MMR 1500 enters the queue"
    def player = new Player(mmr: 1500)

    when: "matchmaking runs"
    def matches = matchmaker.findMatches()

    then: "player is matched with compatible player"
    matches[0].players.contains(player)
}

Test Categories

Unit Tests:
```
src/test/groovy
```
- Fast, isolated tests with mocked dependencies
Integration Tests:
```
src/integrationTest/groovy
```
- Full Spring context with Testcontainers

CI/CD Pipeline

Our GitLab CI/CD pipeline follows DORA best practices with these stages:

Build - Compile the application
Test - Run unit and integration tests in parallel
Quality - Static analysis and code quality checks
Package - Build Docker image
Deploy - Deploy to environments (dev, staging, production)
Verify - Smoke tests after deployment

DORA Metrics Targets

Deployment Frequency: Multiple times per day
Lead Time: Commit to production < 1 hour
MTTR: Mean time to recovery < 1 hour
Change Failure Rate: < 15%

Development Workflow

We follow Kent Beck's TDD + Tidy First approach:

Red: Write a failing test
Green: Write minimum code to pass the test
Refactor: Improve structure (only when tests are green)
Commit: Separate commits for structural vs behavioral changes

Commit Discipline

✅ Commit only when ALL tests pass
✅ No compiler/linter warnings
✅ Single logical unit of work
✅ Clear message indicating structural or behavioral change

Examples:

refactor: extract matchmaking policy to separate class

```
feat: add MMR-based matchmaking
```

Design Principles

CUPID over SOLID (Dan North): Composable, Unix philosophy, Predictable, Idiomatic, Domain-based
Effective Java (Josh Bloch): Immutability, static factories, defensive copies, builders
DDD Patterns: Aggregates, entities, value objects, domain events
Event-Driven: Loose coupling via domain events and Kafka

Project Structure

src/
├── main/
│   ├── java/                    # Production code (Java)
│   │   └── org/robbiemcarthur/multiplayermatchmakerservice/
│   │       ├── player/          # Player bounded context
│   │       ├── matchmaking/     # Matchmaking bounded context
│   │       ├── match/           # Match lifecycle bounded context
│   │       └── gameevents/      # Game events bounded context
│   └── resources/
│       └── application.yml      # Application configuration
├── test/
│   └── groovy/                  # Unit tests (Spock)
└── integrationTest/
    └── groovy/                  # Integration tests (Spock + Testcontainers)

Configuration

Main configuration:

src/main/resources/application.yml

Profile-specific configs:

```
application-dev.yml
```
- Local development
```
application-test.yml
```
- Test environment
```
application-prod.yml
```
- Production

Docker

Build Docker image:

docker build -t multiplayer-matchmaker-service .

Run container:

docker run -p 8080:8080 multiplayer-matchmaker-service

Repository

GitLab (primary): https://gitlab.com/robbiemcarthur/multiplayer-matchmaking-service
CI/CD: GitLab CI/CD with automated testing and deployment

Contributing

Please read CLAUDE.md for development guidelines and architectural decisions.

See GIT_WORKFLOW.md for TDD commit workflow.

License

[Add your license here]

Multiplayer Matchmaker Service

Related Skills

<h1 align="center">

2. Apply Deepthink Protocol (reason about dependencies

- Identify gaps