JavaWorkshop

A multiplayer browser game platform. Players can register, add friends, join a matchmaking queue or invite friends directly, and play TicTacToe, Memory, or Connect 4 in real time.

The backend is built with Spring Boot microservices, game events flow through Apache ActiveMQ, data is persisted in MySQL 8, and the frontend is a React + TypeScript single-page application.

• Backend overview
• Frontend overview
• Database migrations

---

Architecture

┌──────────────┐     HTTP / WebSocket
│   Frontend   │ ──────────────────────────────┐
│  (React/TS)  │                               ▼
└──────────────┘               ┌───────────────────────┐
                               │      GameGateway      │ (:8080)
                               │  Auth · REST · WS     │
                               │  Matchmaking · Friends│
                               └──────────┬────────────┘
                                          │ JMS (ActiveMQ)
               ┌──────────────────────────┼──────────────────────────┐
               ▼                          ▼                          ▼
  ┌────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
  │ TicTacToeService   │    │   MemoryGameService  │    │ Connect4GameService │
  │      (:8081)       │    │       (:8082)        │    │      (:8083)        │
  └────────────────────┘    └──────────────────────┘    └─────────────────────┘
               │                          │                          │
               └──────────────────────────┼──────────────────────────┘
                                          ▼
                                  ┌──────────────┐
                                  │   MySQL 8    │ (:3306)
                                  └──────────────┘

        ┌──────────────────────────────┐
        │  Apache ActiveMQ Classic     │ broker (:61616) · web console (:8161)
        └──────────────────────────────┘

---

Prerequisites

Tool	Minimum version
Docker + Docker Compose	Docker 24+
Java JDK (for local dev only)	21
Node.js + npm (for local dev only)	20

---

Quick Start (Docker Compose)

This is the recommended way to run the full stack.

1. Create your environment file

cp .env.example .env

Open .env and set DB_USERNAME and DB_PASSWORD. Everything else has working defaults.

2. Start all services

docker compose up --build

Service	URL
Frontend	http://localhost
Game Gateway API	http://localhost:8080
Swagger UI	http://localhost:8080/swagger-ui.html
Memory Game Service	http://localhost:8081
Tic-Tac-Toe Service	http://localhost:8082
ActiveMQ Web Console	http://localhost:8161

3. Stop services

docker compose down

To also remove persisted database data:

docker compose down -v

IDE tip: IntelliJ can inject .env variables automatically with the EnvFile plugin. If you run individual services outside Docker, configure that plugin to load the root .env.

Markdown linting/formatting: From the repo root, run node scripts/docs.js lint to check and node scripts/docs.js format to fix. Rules are defined in .markdownlint.json.

Recommended IntelliJ plugins

Plugin	Purpose
EnvFile	Load .env into run configurations
Docker	docker-compose.yml editing and run support (built into Ultimate)

---

Local Development

Use this when you want to run services individually in your IDE and iterate quickly.

1. One-time setup

node setup.js

This will:

• Check for required tools (Java 21+, Maven, Node 18+)
• Create .env from .env.example if it doesn't exist
• Check that all mandatory env variables are set
• Build all backend Maven modules (mvn clean install -DskipTests)
• Install frontend npm dependencies

2. Start infrastructure (MySQL + ActiveMQ only)

docker compose up mysql activemq

3. Run backend services

Each service reads DB_URL, DB_USERNAME, DB_PASSWORD, and ACTIVEMQ_URL from the environment. The recommended approach is to use the EnvFile IntelliJ plugin to inject the root .env into each run configuration.

To run from the terminal instead, first export the variables into your shell session:

# bash / macOS / Git Bash
set -a && source .env && set +a

# PowerShell
Get-Content .env | Where-Object { $_ -notmatch '^#' -and $_ -match '=' } |
  ForEach-Object { $k,$v = $_ -split '=',2; [System.Environment]::SetEnvironmentVariable($k,$v) }

Then start the services:

# from backend/
cd GameGateWay          && mvn spring-boot:run &
cd TicTacToeGameService && mvn spring-boot:run &
cd MemoryGameService    && mvn spring-boot:run &
cd Connect4GameService  && mvn spring-boot:run &

4. Run the frontend

cd frontend
REACT_APP_API_BASE=http://localhost:8080 npm start

The dev server starts at http://localhost:3000.