# To Be Played (TBP) - Core Service

This is the Core Service for the "To Be Played" project. It acts as the central modulith, handling all business logic in vertical micro-service ready slices.

## 🚀 Tech Stack

* **Language:** Java 25
* **Framework:** Spring Boot 4.1.x
* **Security:** Spring Security & JSON Web Tokens (JWT)
* **Database:** PostgreSQL 17
* **Migrations:** Flyway
* **Observability:** Spring Boot Actuator & Micrometer (Prometheus)
* **Build Tool:** Maven Wrapper (`mvnw`)
* **CI/CD:** Gitea Actions (Forgejo)

## 🏗️ Architecture (Clean Architecture)

The project strictly follows a Domain-Driven / Clean Architecture (Ports & Adapters) approach to ensure high maintainability and testability. The codebase is divided into three main layers to prevent framework lock-in and keep business logic isolated.

### Layer Breakdown

1. **API / Web Layer (`api`)**
    * Contains REST endpoints, DTOs (`Request`/`Response` records), and Global Exception Handlers.
    * Uses `ApiMapper` to map between DTOs and Domain Models.
    * **Rule:** This layer delegates to the Service layer and never accesses persistence directly.

2. **Business / Core Layer (`model`, `service`, `exception`)**
    * The heart of the application. Contains pure Java classes (Models) and Business Logic (Services).
    * Throws specific business exceptions (e.g., `InvalidCredentialsException`).
    * **Rule:** This layer has **no dependencies** on the API or Persistence layer. It defines interfaces that the persistence layer must implement.

3. **Persistence Layer (`persistence`)**
    * Handles database operations. Contains JPA Entities (`UserEntity`), Spring Data Repositories, and the `EntityMapper`.
    * Implements the interfaces defined in the Domain layer.
    * **Rule:** Entities never leak into the API layer.

*Note: Future implementations will include ArchUnit tests to automatically enforce these architectural boundaries during the CI pipeline.*

## ⚙️ Local Development

Running the application locally is fully automated via Spring Boot's Docker Compose Support.

### Prerequisites

* Java 25 installed
* Docker & Docker Compose running

### How to start

1. Simply run the application from your IDE (e.g., IntelliJ) via the `CoreServiceApplication.java` main class.
2. Spring Boot will automatically detect the `compose.yaml` and spin up a local PostgreSQL container (`tbp_db_local`) on port `5432`.
3. **Flyway** will automatically apply all database migrations located in `src/main/resources/db/migration`.
4. The application will be available at `http://localhost:8090`.

To stop the environment and clean the database volume (if needed):

```bash
docker compose down -v
```

## 🔐 API Versioning

All API endpoints utilize Query Parameter Versioning to keep URLs clean and manageable.
Example: GET /api/users/me?v=1

## 🐳 CI/CD Pipeline

The project uses Gitea Actions for Continuous Integration and Deployment.

Quality Gate: Runs ./mvnw clean verify to ensure tests and builds pass.

Docker Build: Packages the application using a multi-stage Dockerfile.

Registry: Pushes the lightweight Alpine-based image to the private Gitea container registry (git.andreas-dahm.eu/lobo_corp/tbp-core-service:latest).

## 📈 Observability

Metrics and health checks are exposed out-of-the-box via Spring Boot Actuator:

Health: http://localhost:8090/actuator/health

Prometheus Metrics: http://localhost:8090/actuator/prometheus