Contents

• Introduction
• Quick Start
  • Prerequisites
  • Setting up common mock dependencies
  • Running the application
  • Backend API documentation
  • Architectural Design Decisions
• Profiles overview
  • Useful Maven profiles (compile-time)
  • Useful Spring profiles (run-time)
  • Docker Compose profiles (dependencies)
• Running test suites
  • Unit tests (backend)
  • Frontend tests
  • End-to-End (E2E) tests
• Contributing to the documentation

Introduction

Welcome to the Backity developer documentation!

Whether you’re contributing to the backend, frontend, or documentation, this guide will outline everything you need to know.

Backity uses Domain-Driven Design (DDD) and the Ports & Adapters (Hexagonal) architecture. Before diving in, it’s a good idea to become familiar with these concepts:

• “Introduction to DDD” - InfoQ
• “Ports & Adapters (aka hexagonal) architecture explained” - codesoapbox.dev
• “Hexagonal architecture” - Alistair Cockburn

Quick Start

Prerequisites

Make sure you have the following installed:

• JDK (see pom.xml for the version)
• Docker,
• Docker Compose (for dependencies when running the application locally, for running SonarQube)
• NodeJs and npm (for building frontend; see frontend/src/main/angular/package.json for versions)
• (Optional) A Chromium-based browser for frontend testing.

Setting up common mock dependencies

To start the common mock dependencies, use the following command in the root of the repository:

docker compose -f docker/e2e/docker-compose.yml --env-file docker/e2e/.env up -d

See Profiles overview for more mock dependencies.

Running the application

1. Build the project: ./mvnw clean package
2. Start the backend: ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev,dev-provider-api
3. Access the application at http://localhost:8080.

The frontend is automatically bundled into the backend jar when the project is built, so you don’t need to start the frontend unless you need it to automatically react to changes in its code.

To run the Angular frontend independently for faster iteration:

cd frontend/src/main/angular
ng serve

Access the frontend at http://localhost:4200. It reloads automatically, which speeds up your work.

Backend API documentation

The Swagger UI page is available at http://localhost:8080/swagger-ui.html.

The OpenAPI description is available at the following urls:

• http://localhost:8080/v3/api-docs - in json format
• http://localhost:8080/v3/api-docs.yaml - in yml format

Architectural Design Decisions

Architectural Decision Records (ADRs) document the key design choices for the project. They are useful because:

• They prevent repeating past mistakes or re-discussing settled decisions,
• They help understand why certain approaches were chosen,
• They ensure architectural consistency.

Whenever possible, they are written as ArchUnit tests. When not practical, they are documented in text form and can be found in the developer documentation.

Take a moment to review these before diving in to ensure your contributions align with the established design principles.

Profiles overview

Backity supports multiple profiles for flexible configurations during development and testing.

• Use Maven profiles with -P,
• Use Spring profiles with -Dspring-boot.run.profiles,
• Use Docker Compose profiles with --profile.

Examples:

./mvnw clean verify -Pangular-client-code-gen
/mvnw spring-boot:run -Dspring-boot.run.profiles=dev,dev-provider-api
docker compose --profile s3 -f docker/e2e/docker-compose.yml --env-file docker/e2e/.env up -d

Useful Maven profiles (compile-time)

Profile	Description
frontend-sonar	Runs only a sonar analysis for the frontend module.
angular-client-code-gen	Generates client code from the API specification.

Useful Spring profiles (run-time)

Profile	Description
dev	Allows things like handling requests from http://localhost:4200/ for local development.
dev-provider-api	Uses mock APIs for Game Providers (provided by the mockserver Docker container).
dev-s3	Uses a mock S3 provider for file storage (provided by the localstack Docker container).

Docker Compose profiles (dependencies)

Profile	Description
s3	Starts a mock S3 server.

Running test suites

Unit tests (backend)

Run backend unit tests with:

cd backend
../mvnw test

Run all backend tests (including integration tests) with:

cd backend
../mvnw verify

Frontend tests

Run Angular frontend tests with:

cd frontend/src/main/angular
ng test

End-to-End (E2E) tests

Ensure the application is running, then execute:

cd e2e
../mvnw test

Contributing to the documentation

This documentation uses Jekyll via GitHub Pages with Just the Docs as the theme and is stored in the project repository under the docs folder.

You can contribute to it by creating a Pull Request, just like you would with any other part of this project.

---

Table of contents

• Advanced topics