GameStats API

A backend system built with Spring Boot that manages game data.

---

Table of Contents

• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Run Locally
  • Run PostgreSQL with Docker Compose
• Configuration
• API Overview
  • Players
  • Games
  • Matches
• Data Model
• Swagger / OpenAPI
• Roadmap / Ideas
• License

---

Features

• Spring Boot 3.5 (RESTful API architecture)
• PostgreSQL 17 with JPA / Hibernate ORM
• Layered design (Controller–Service–Repository)
• DTO mapping for input models
• Input validation and entity constraints
• Swagger / OpenAPI documentation
• Docker Compose for database containerization
• Logging and SQL formatting enabled
• Extensible modular structure for future features

---

Tech Stack

• Java 25 (via Spring Boot parent)
• Spring Boot 3.5.7
  • spring-boot-starter-web
  • spring-boot-starter-data-jpa
  • Validation via Hibernate Validator / Jakarta
• PostgreSQL 17
• springdoc-openapi (Swagger UI)
• Maven

See pom.xml for exact versions.

---

Project Structure

src/
 └─ main/
    ├─ java/com/dev/gamestats
    │   ├─ controllers/   # REST controllers
    │   ├─ model/         # Entities + DTOs (Game, Player, Match; GameIn, PlayerIn, MatchIn)
    │   ├─ repo/          # Spring Data repositories (CrudRepository)
    │   └─ services/      # Service layer
    └─ resources/
        └─ application.properties

Note: You also have a docker-compose.yml in the project root.

---

Getting Started

Prerequisites

• JDK 25 (or compatible with Spring Boot 3.5.x)
• Maven 3.9+ (or use the provided mvnw wrapper)
• Docker (for running PostgreSQL)

---

Run Locally

1. Start PostgreSQL (see next section).

2. Update src/main/resources/application.properties if needed (DB URL/credentials).

3. Build & run the app:

   ./mvnw spring-boot:run
   # or
   mvn spring-boot:run

4. The app will be available at http://localhost:8080.

---

Run PostgreSQL with Docker Compose

A docker-compose.yml file is already included in the project root.

To start PostgreSQL:

docker-compose up -d

This launches a PostgreSQL 17 container on host port 5434 with persistent data stored in a named Docker volume.

To stop it:

docker-compose down

---

Configuration

Default application properties (src/main/resources/application.properties):

spring.application.name=GameStats

# Database
spring.datasource.url=jdbc:postgresql://localhost:5434/gamestats
spring.datasource.username=gamestats
spring.datasource.password=gamestats
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA / Hibernate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

For production, switch ddl-auto to validate or none and manage schema via migrations.

---

API Overview

Base path: http://localhost:8080/api

Players

Resource: /player

• POST /api/player

  {
    "firstName": "Alice",
    "lastName": "Nguyen",
    "countryCode": "US"
  }

• GET /api/player/

• GET /api/player/{playerId}

• PUT /api/player/{playerId}

• DELETE /api/player/{playerId}

---

Games

Resource: /game

• POST /api/game

  {
    "name": "Chess",
    "ruleSet": "Standard FIDE rules"
  }

• GET /api/game/

• GET /api/game/{gameId}

• PUT /api/game/{gameId}

• DELETE /api/game/{gameId}

---

Matches

Resource: /match

• POST /api/match

  {
    "game_id": 1,
    "player1_id": 10,
    "player2_id": 12,
    "winner_id": 12,
    "playedAt": "Home",
    "score1": 200,
    "score2": 280,
    "notes": "gg wp!"
  }

• GET /api/match/

• GET /api/match/{matchId}

• PUT /api/match/{matchId}

• DELETE /api/match/{matchId}

Validation & Integrity

• countryCode must be ISO-2 format (e.g., US, IL).
• No self-matches: player1_id ≠ player2_id.
• Winner must be either player1_id or player2_id.
  These constraints are enforced at the DB level via @Check.

---

Data Model

Entity Relationship Diagram — GameStats database.

---

Swagger / OpenAPI

If springdoc-openapi is included, the documentation is available at:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

Tip: Add these URLs as bookmarks for faster testing.

---

Roadmap

• Add paging & filtering
• Add CLI client for demonstration
• Integrate JWT-based authentication
• Implement unit and integration tests

---

Author

Developed by Daniel Katzman.