Public Access
lobo
04dcab45da
Add project bootstrap for build, CI/CD, and local development. Introduces Maven Wrapper (mvnw, mvnw.cmd, .mvn/wrapper), multi-stage Dockerfile, docker-compose files (compose.yaml, docker-compose.dev.yml), .env, banner and README. Adds Gitea Actions workflow to build, test and push container images. Update application.yml (port -> 8090, virtual threads, API versioning, management/actuator/prometheus settings, Steam API config) and add application-dev.yml for local overrides. Extend pom.xml with caching, observability (actuator, micrometer/prometheus), testing/dev dependencies (testcontainers, devtools, additional spring test modules) to support CI and local testing.
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 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. **Controller / Web Layer (`controller`)**
|
|
* 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. **Domain / 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 Controller 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 Controller 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 |