Map Service

Provides maps in the Microservice Dungeon system.

Architecture

The service follows hexagonal architecture (ports and adapters) principles, using Spring Modulith for module discipline and jMolecules for DDD annotations.

• Domain core: Aggregates (map, planet, maptemplate, game) contain the business logic and domain services. Domain services act as the ports — no explicit port interfaces are introduced.
• Driving adapters: Translate external stimuli into domain calls. rest/ handles HTTP requests, usecases/infrastructure/ handles Kafka events.
• Driven adapters: Translate domain calls into infrastructure. persistence/ sub-packages handle database access, outbox writers handle event publishing.

The domain never depends on adapter concerns. Adapters freely depend on domain services. REST controllers and event listeners are cross-cutting — they live in top-level packages (rest/, usecases/) rather than inside aggregate packages, because their payload structure is shaped by client and integration needs, not by aggregate boundaries.

Test Structure

Tests are separated into three categories by source directory, allowing them to be run independently.

Unit Tests (src/test)

Pure unit tests that run without Spring or any external infrastructure. These are designed to be fast (sub-second for the full suite).

• Run via Maven: mvn test
• Run in IntelliJ: Right-click src/test/java
• Naming convention: *Test.java
• Maven plugin: maven-surefire-plugin (runs in the test phase)

Integration Tests (src/testIntegration)

Tests that require the Spring application context to start, but do not require any external infrastructure like database or Kafka message broker. The integration tests includes Spring Modulith architecture verification and ArchUnit rule checks that need Spring’s classpath scanning.

The reason that these tests are handled separately is that they take longer to run, usually a minute or so, so that you probably don’t run them after each step of your development. On the other hand, they still can be run locally without requiring any external infrastructure, so that they are a good means of verifying the code integrity before a commit, or provide an entry point for new developers looking at the code and trying to understand it.

• Run via Maven: mvn verify (runs unit tests first, then integration tests)
• Run in IntelliJ: Right-click src/testIntegration/java
• Naming convention: *IT.java
• Maven plugin: maven-failsafe-plugin (runs in the integration-test phase)
• Configuration: src/testIntegration/resources/application.yml

Note: As of now (2025), if you run these integration tests from within JetBrains IntelliJ, you need to provide explicit instructions to execute the byte body plugin for the Spring Modulith tags. This is due to the fact that IntelliJ does not use the standard Maven implementation, but its own native implementation, which does not read the plug-in section of the POM XML correctly. See these instructions for the configuration in IntelliJ.

System Tests (src/testSystem)

Tests that require the Spring application context and external infrastructure, such as a PostgreSQL database. The database is started and stopped automatically via Testcontainers, so Docker must be running on your machine.

• Run via Maven: mvn verify (runs unit tests first, then integration and system tests)
• Run in IntelliJ: Right-click src/testSystem/java
• Naming convention: *ST.java
• Maven plugin: maven-failsafe-plugin (runs in the integration-test phase)
• Configuration: src/testSystem/resources/application.yml
• Prerequisite: Docker engine must be running

Note: The same IntelliJ ByteBuddy configuration required for integration tests also applies here. See these instructions for the configuration in IntelliJ.

Local Development

The application uses PostgreSQL as its database. For local development, a docker-compose.yml is provided that starts a PostgreSQL 17 instance with matching credentials.

docker-compose up -d
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

The dev profile (application-dev.yml) provides default connection settings that match the Docker Compose configuration (localhost:5432, database/user/password all set to map), so no environment variables need to be set.

In production, the main application.yml expects the connection details to be provided via environment variables (POSTGRES_HOST, POSTGRES_PORT, POSTGRES_TABLE, POSTGRES_USER, POSTGRES_PASS).