Public Access
lobo
2a5839b736
Move domain packages into a new modules.* hierarchy and rename controller packages to api.* across login, registration, and user modules. Update package declarations and imports (including shared.api DTOs and JwtService -> modules login TokenGenerator), adjust tests and persistence/mapper paths accordingly, and apply minor formatting fixes (missing EOF newlines). This reorganizes the project to better separate API surface and module boundaries.
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# To Be Played (TBP) - Authentication Service
|
|
|
|
This is the Authentication and User Management Service for the "To Be Played" project. It acts as the central identity provider, handling user authentication, JWT generation, and profile management for the TBP frontend.
|
|
|
|
## 🚀 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 `AuthServiceApplication.java` main class.
|
|
2. Spring Boot will automatically detect the `compose.yaml` and spin up a local PostgreSQL container (`tbp_auth_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:8080`.
|
|
|
|
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-auth-service:latest).
|
|
|
|
## 📈 Observability
|
|
|
|
Metrics and health checks are exposed out-of-the-box via Spring Boot Actuator:
|
|
|
|
Health: http://localhost:8080/actuator/health
|
|
|
|
Prometheus Metrics: http://localhost:8080/actuator/prometheus |