2 Backend

Jan Klattenhoff edited this page 2025-03-19 12:02:22 +01:00

Table of Contents

• Backend Architecture
• Tech Stack
• Project Structure
• Key Modules
• User Management
• Deposit System
• Security
• Exception Handling
• API Endpoints
• User API
• Deposit API
• Health API
• Authentication Flow
• Database Schema
• User Table
• Development Workflow
• Code Style Guidelines
• Testing

Backend Architecture

This page documents the backend architecture of the Casino Gaming Platform.

Tech Stack

• Framework: Spring Boot (Java)
• Database: PostgreSQL
• Authentication: Keycloak integration
• Build Tool: Gradle
• API Documentation: OpenAPI/Swagger
• Payment Processing: Stripe API

Project Structure

The backend follows a domain-driven design approach with the following structure:

src/
├── main/
│   ├── java/
│   │   └── de/
│   │       └── szut/
│   │           └── casino/
│   │               ├── CasinoApplication.java
│   │               ├── config/
│   │               │   └── OpenAPIConfiguration.java
│   │               ├── deposit/
│   │               │   ├── DepositController.java
│   │               │   └── dto/
│   │               │       ├── AmountDto.java
│   │               │       └── SessionIdDto.java
│   │               ├── exceptionHandling/
│   │               │   ├── ErrorDetails.java
│   │               │   ├── GlobalExceptionHandler.java
│   │               │   └── ResourceNotFoundException.java
│   │               ├── health/
│   │               │   └── HealthController.java
│   │               ├── security/
│   │               │   ├── KeycloakLogoutHandler.java
│   │               │   └── KeycloakSecurityConfig.java
│   │               └── user/
│   │                   ├── UserController.java
│   │                   ├── UserEntity.java
│   │                   ├── UserMappingService.java
│   │                   ├── UserRepository.java
│   │                   ├── UserService.java
│   │                   └── dto/
│   │                       ├── CreateUserDto.java
│   │                       ├── GetUserDto.java
│   │                       └── KeycloakUserDto.java
│   └── resources/
│       └── application.properties
└── test/
    └── java/
        └── de/
            └── szut/
                └── casino/
                    ├── Lf8StarterApplicationTests.java
                    ├── health/
                    │   └── HealthControllerTest.java
                    └── user/
                        └── UserControllerTest.java

Key Modules

User Management

The user module handles:

• User registration and profile management
• Balance tracking
• User data retrieval and updates

Key components:

• UserController: REST endpoints for user operations
• UserService: Business logic for user operations
• UserRepository: Data access layer
• UserEntity: Database entity for user data

Deposit System

The deposit module manages virtual currency deposits:

• Integration with Stripe for payment processing
• Creation of payment sessions
• Verification of successful payments
• Updating user balances

Key components:

• DepositController: REST endpoints for deposit operations
• AmountDto: Data transfer object for deposit amounts
• SessionIdDto: Data transfer object for Stripe session IDs

Security

The security module handles authentication and authorization:

• Integration with Keycloak for identity management
• JWT token validation
• Role-based access control
• Logout handling

Key components:

• KeycloakSecurityConfig: Configuration for Keycloak integration
• KeycloakLogoutHandler: Handles user logout flow

Exception Handling

Global exception handling for consistent error responses:

• GlobalExceptionHandler: Central exception handler
• ErrorDetails: Standardized error response format
• ResourceNotFoundException: Custom exception for missing resources

API Endpoints

The backend exposes the following main API endpoints:

User API

• GET /api/users/{id}: Get user by ID
• POST /api/users: Create a new user
• PUT /api/users/{id}: Update user information
• GET /api/users/me: Get the current authenticated user

Deposit API

• POST /api/deposits/create-session: Create a Stripe payment session
• POST /api/deposits/verify: Verify a completed payment

Health API

• GET /api/health: Health check endpoint

Authentication Flow

1. User authenticates through the frontend application
2. Frontend receives JWT tokens from Keycloak
3. Backend validates tokens for API requests
4. User info is extracted from validated tokens
5. Authorization is enforced based on token roles

Database Schema

User Table

Column	Type	Description
id	UUID	Primary key
username	VARCHAR	User's username
email	VARCHAR	User's email address
balance	DECIMAL	User's virtual currency balance
created_at	TIMESTAMP	Account creation timestamp
updated_at	TIMESTAMP	Last update timestamp

Development Workflow

1. Start the backend with:

   ./gradlew bootRun
   

2. The API will be available at: http://localhost:8080

3. Swagger documentation: http://localhost:8080/swagger

4. Run tests:

   ./gradlew test
   

5. Run specific test class:

   ./gradlew test --tests "FullyQualifiedClassName"
   

6. Build the project:

   ./gradlew build
   

   or for a clean build:

   ./gradlew clean build
   

Code Style Guidelines

• Use PascalCase for classes with descriptive suffixes (Controller, Service, Entity)
• Use camelCase for methods and variables
• Follow domain-driven package organization
• Prefix DTOs with domain and suffix with "Dto"
• Use Spring's global exception handling with custom exceptions

Testing

The backend includes:

• Unit tests for service and controller layers
• Integration tests for API endpoints
• Mock tests using Mockito

Run tests with:

./gradlew test

Check code style with:

./gradlew checkstyleMain checkstyleTest