SZUT/casino
SZUT/casino
Archived
3
1
Fork 0
Code Issues Pull requests 2 Releases 162 Packages 2 Wiki Activity Actions

update

Jan K9f 2025-06-04 09:36:55 +02:00
commit a90e821cb7
Signed by: jank
GPG key ID: 22BEAC760B3333D6
12 changed files with 1439 additions and 386 deletions
Download patch file Download diff file Expand all files Collapse all files

418
Authentication-and-Authorization.md

@ -4,241 +4,403 @@ This page documents the authentication and authorization system of the Casino Ga
## Overview
The Casino Gaming Platform uses Keycloak as its identity and access management solution. This provides:
The Casino Gaming Platform uses a hybrid authentication system combining custom JWT tokens with OAuth2 social login integration. This provides:
- Secure user authentication
- Single sign-on (SSO) capability
- Secure user authentication with email/password
- OAuth2 social login (GitHub, Google)
- JWT token-based authorization
- Email verification system
- Password recovery functionality
- User profile management
- Role-based access control
- Token-based authorization
- Real-time session management
## Architecture
```
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ │ │ │ │ │
│ Frontend │◄──────► Keycloak │◄──────► Backend │
│ (Angular) │ │ │ │ (Spring Boot) │
│ │ │ │ │ │
└────────────────┘ └────────────────┘ └────────────────┘
▲ │
│ │
└──────────────────────────────────────────────────┘
(API calls with JWT token)
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Frontend │ │ OAuth2 Providers│ │ Backend │
│ (Angular 20) │ │ (GitHub, Google) │ │ (Spring Boot 3) │
│ │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌───────────────────────▼───────────────────────┐
│ JWT Token Management │
│ - Access Tokens (15 min) │
│ - Refresh Tokens (7 days) │
│ - Email Verification Tokens │
│ - Password Reset Tokens │
└───────────────────────────────────────────────┘
```
## Keycloak Configuration
## Authentication Configuration
### Realm Setup
### JWT Token Configuration
The platform uses a dedicated Keycloak realm named `lf12-realm`:
- **Access Token Lifespan**: 15 minutes
- **Refresh Token Lifespan**: 7 days
- **Email Verification Token**: 24 hours
- **Password Reset Token**: 1 hour
- **Algorithm**: RS256 (RSA + SHA-256)
- **Client ID**: `casino-frontend`
- **Access Type**: Public
- **Valid Redirect URIs**:
- `http://localhost:4200/*`
- `http://casino.example.com/*` (for production)
- **Web Origins**: `+` (allows all origins from Valid Redirect URIs)
### OAuth2 Provider Configuration
### User Roles
#### GitHub OAuth2
- **Client Type**: Public
- **Scope**: `user:email`
- **Redirect URI**: `http://localhost:4200/auth/oauth-callback`
#### Google OAuth2
- **Client Type**: Public
- **Scope**: `openid email profile`
- **Redirect URI**: `http://localhost:4200/auth/oauth-callback`
### User Roles and Permissions
The following user roles are defined:
- **user**: Basic authenticated user
- **admin**: Administrative user with management capabilities
- **vip**: Users with premium access (higher limits, special games)
- **USER**: Basic authenticated user with game access
- **ADMIN**: Administrative user with management capabilities
- **MODERATOR**: User with limited admin capabilities
### Token Configuration
### Security Configuration
- **Access Token Lifespan**: 5 minutes
- **Refresh Token Lifespan**: 30 days
- **ID Token Lifespan**: 1 hour
- **Password Requirements**: Minimum 8 characters, alphanumeric
- **Email Verification**: Required for account activation
- **Session Management**: Stateless JWT-based authentication
- **CORS Configuration**: Restricted to frontend domain
## Authentication Flow
### Frontend Authentication
### Email/Password Authentication
1. **Login Initiation**:
- User clicks "Login" button on the frontend
- Application redirects to Keycloak login page
1. **User Registration**:
- User fills out registration form
- Backend validates email uniqueness
- Account created with `email_verified: false`
- Verification email sent with unique token
- User clicks verification link to activate account
2. **Keycloak Authentication**:
- User enters credentials on Keycloak login page
- Keycloak authenticates the user
- Keycloak redirects back to the application with authorization code
2. **User Login**:
- User enters email and password
- Backend validates credentials
- JWT access and refresh tokens generated
- Tokens returned to frontend and stored in localStorage
- User redirected to home dashboard
3. **Token Exchange**:
- Frontend exchanges authorization code for tokens
- Frontend stores tokens in secure storage
- User is redirected to the home page
3. **Token Management**:
- Access token included in API requests via HTTP interceptor
- Automatic token refresh when access token expires
- Logout clears tokens and invalidates refresh token
4. **Auto-login with Silent Check-SSO**:
- Application uses silent-check-sso.html for quiet refresh
- If user has an active Keycloak session, they're automatically logged in
### OAuth2 Social Login Flow
### Backend Authentication
1. **GitHub/Google Login**:
- User clicks social login button
- Frontend redirects to OAuth2 provider
- User authorizes application
- Provider redirects to callback with authorization code
1. **Token Validation**:
- Frontend includes the JWT token in Authorization header
- Backend validates the token signature using Keycloak's public key
- Backend extracts user information and roles from the token
2. **OAuth2 Token Exchange**:
- Frontend sends authorization code to backend
- Backend exchanges code for user profile data
- Account created or linked if existing
- JWT tokens generated and returned
- User logged in and redirected to home
### Password Recovery Flow
1. **Password Reset Request**:
- User enters email address
- Backend generates password reset token
- Reset email sent with secure link
- User clicks link to access reset form
2. **Password Reset**:
- User enters new password
- Backend validates reset token
- Password updated and tokens invalidated
- User must log in with new password
### Backend Token Validation
1. **Token Verification**:
- Frontend includes JWT token in Authorization header
- Backend validates token signature and expiration
- User information extracted from token claims
- Request proceeds if token valid
2. **Token Refresh**:
- When access token expires, frontend uses refresh token to get a new one
- If refresh token is invalid, user is redirected to login
- When access token expires, frontend uses refresh token
- Backend validates refresh token and issues new access token
- If refresh token invalid, user redirected to login
## Authorization
### Frontend Authorization
The Angular application uses route guards to protect routes:
The Angular application uses route guards and service-based authentication:
```typescript
// auth.guard.ts
@Injectable({
providedIn: 'root'
})
export class AuthGuard {
constructor(private router: Router) {}
export class AuthGuard implements CanActivate {
constructor(
private authService: AuthService,
private router: Router
) {}
canActivate(): boolean {
if (!this.isAuthenticated()) {
this.router.navigate(['/landing']);
return false;
if (this.authService.isAuthenticated()) {
return true;
}
return true;
this.router.navigate(['/auth/login']);
return false;
}
}
// auth.service.ts
@Injectable({
providedIn: 'root'
})
export class AuthService {
private tokenKey = 'access_token';
private refreshTokenKey = 'refresh_token';
isAuthenticated(): boolean {
// Check for valid token
const token = localStorage.getItem(this.tokenKey);
return token && !this.isTokenExpired(token);
}
getToken(): string | null {
return localStorage.getItem(this.tokenKey);
}
logout(): void {
localStorage.removeItem(this.tokenKey);
localStorage.removeItem(this.refreshTokenKey);
this.router.navigate(['/auth/login']);
}
}
```
Protected routes are configured in the routing module:
Protected routes are configured with guards:
```typescript
const routes: Routes = [
{ path: '', component: LandingComponent },
{ path: '', redirectTo: '/home', pathMatch: 'full' },
{ path: 'auth', loadChildren: () => import('./auth/auth.module') },
{ path: 'home', component: HomeComponent, canActivate: [AuthGuard] },
{ path: 'games', loadChildren: () => import('./games/games.module'), canActivate: [AuthGuard] },
{ path: 'deposit', component: DepositComponent, canActivate: [AuthGuard] }
];
```
### Backend Authorization
The Spring Boot backend uses Spring Security with Keycloak adapter:
The Spring Boot backend uses Spring Security with custom JWT authentication:
```java
@Configuration
@EnableWebSecurity
public class KeycloakSecurityConfig extends WebSecurityConfigurerAdapter {
public class SecurityConfig {
@Override
protected void configure(HttpSecurity http) throws Exception {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeRequests()
.antMatchers("/api/health").permitAll()
.antMatchers("/api/users/**").hasRole("user")
.antMatchers("/api/admin/**").hasRole("admin")
.anyRequest().authenticated()
.and()
.oauth2ResourceServer().jwt();
.csrf(csrf -> csrf.disable())
.cors(cors -> cors.configurationSource(corsConfigurationSource()))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/auth/**").permitAll()
.requestMatchers("/api/health").permitAll()
.requestMatchers(HttpMethod.POST, "/api/deposits/webhook").permitAll()
.requestMatchers("/api/admin/**").hasRole("ADMIN")
.anyRequest().authenticated()
)
.sessionManagement(session ->
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
)
.addFilterBefore(jwtAuthenticationFilter(),
UsernamePasswordAuthenticationFilter.class);
return http.build();
}
}
```
## User Registration
## User Registration and Management
Users can register in two ways:
### Registration Methods
1. **Self-registration through frontend**:
- User clicks "Register" on frontend
- User completes registration form
- Account is created in Keycloak
- User profile is created in application database
1. **Email/Password Registration**:
- User fills out registration form with username, email, password
- Backend validates email uniqueness and password strength
- User account created with email verification required
- Verification email sent with activation link
- User must verify email before full account access
2. **Admin-created accounts**:
- Admins can create users through Keycloak Admin Console
- Backend syncs new users from Keycloak to application database
2. **OAuth2 Social Registration**:
- User initiates social login (GitHub/Google)
- Backend receives user profile from OAuth2 provider
- Account automatically created and verified
- User logged in immediately after authorization
3. **Account Linking**:
- Existing users can link social accounts to their profile
- Multiple login methods for same account
- Profile consolidation and enhanced security
### User Profile Management
- **Profile Updates**: Users can update username, email (requires re-verification)
- **Password Changes**: Secure password update with current password verification
- **Account Deletion**: Soft delete with data retention policy
- **Session Management**: View and revoke active sessions
## Security Considerations
### Token Storage
### Token Storage and Security
- Access and refresh tokens are stored in browser's Local Storage
- ID token contains user profile information
- No sensitive information is stored in tokens
- **Access Tokens**: Stored in browser localStorage with 15-minute expiration
- **Refresh Tokens**: Stored in localStorage with 7-day expiration
- **Token Content**: Contains user ID, roles, and expiration (no sensitive data)
- **Automatic Cleanup**: Expired tokens automatically removed
- **Security Headers**: CORS, CSP, and HSTS configured for production
### CSRF Protection
- Angular includes anti-CSRF token with requests
- Spring Security validates CSRF tokens on state-changing operations
- CSRF protection disabled for stateless JWT authentication
- CORS configured to restrict cross-origin requests
- SameSite cookie policy for enhanced security
### Session Management
- JWT token-based authentication is stateless
- Keycloak manages session state
- Session timeout can be configured in Keycloak
- **Stateless Authentication**: JWT tokens eliminate server-side session storage
- **Token Refresh**: Automatic refresh of access tokens using refresh tokens
- **Session Timeout**: Configurable token expiration times
- **Multi-device Support**: Users can be logged in on multiple devices
- **Logout**: Invalidates refresh token and clears client-side tokens
## Testing Authentication
## API Testing and Development
### Obtaining a Test Token
### Obtaining Test Tokens
For API testing, obtain a bearer token:
For API testing, authenticate via the API:
1. Open `requests/getBearerToken.http`
2. Click the green arrow next to the request
3. Copy the `access_token` from the response
1. **Register Test User**:
```bash
POST /api/auth/register
{
"username": "testuser",
"email": "test@example.com",
"password": "password123"
}
```
### Using Swagger with Authentication
2. **Login for Token**:
```bash
POST /api/auth/login
{
"email": "test@example.com",
"password": "password123"
}
```
1. Open Swagger UI at http://localhost:8080/swagger
3. **Use Access Token**:
```bash
Authorization: Bearer <access_token>
```
### Swagger API Documentation
1. Open Swagger UI at http://localhost:8080/swagger-ui.html
2. Click "Authorize" button
3. Enter the bearer token
4. Test API endpoints with authentication
3. Enter the JWT bearer token (include "Bearer " prefix)
4. Test authenticated API endpoints
### Development Tools
- **Mailpit**: Email testing at http://localhost:8025
- **Database Console**: H2 console for development database inspection
- **Actuator Endpoints**: Health checks and metrics at `/actuator`
## Logout Flow
1. **Frontend Logout**:
- User clicks "Logout" button
- Frontend clears local tokens
- Frontend redirects to Keycloak logout endpoint
1. **User-Initiated Logout**:
- User clicks "Logout" button in application
- Frontend calls logout API endpoint
- Backend invalidates refresh token in database
2. **Keycloak Logout**:
- Keycloak invalidates the session
- Keycloak redirects back to application
2. **Token Cleanup**:
- Frontend clears access and refresh tokens from localStorage
- HTTP interceptor stops including authorization headers
- User redirected to login page
3. **Backend Logout Handling**:
- `KeycloakLogoutHandler` processes logout events
- Any necessary cleanup is performed
3. **Automatic Logout**:
- When refresh token expires or is invalid
- When access token cannot be refreshed
- Authentication errors trigger automatic logout
4. **Security Logout**:
- Backend can invalidate all user sessions
- Password changes trigger logout from all devices
- Suspicious activity can trigger forced logout
## Troubleshooting
### Common Issues
1. **"Invalid token" errors**:
- Check token expiration
- Verify Keycloak is running
- Check time synchronization between services
- Check token expiration time
- Verify JWT secret configuration
- Ensure system clocks are synchronized
- Check token format (Bearer prefix)
2. **"Insufficient permissions" errors**:
2. **"Access denied" errors**:
- Verify user has required roles
- Check role mapping in Keycloak
- Check endpoint security configuration
- Ensure token contains correct claims
3. **"Invalid redirect URI" errors**:
- Ensure redirect URI is configured in Keycloak client
3. **OAuth2 authentication failures**:
- Verify OAuth2 client credentials
- Check redirect URI configuration
- Ensure OAuth2 provider is accessible
4. **Email verification issues**:
- Check email service configuration
- Verify SMTP settings in development
- Check Mailpit for sent emails
### Debugging Tips
1. **Examine token contents**:
- Use [jwt.io](https://jwt.io) to decode tokens
- Check audience, issuer, and claims
- Check claims, expiration, and signature
- Verify issuer and audience values
2. **Check Keycloak logs**:
- Use `docker-compose logs keycloak_lf12`
- Look for authentication errors
2. **Check application logs**:
- Backend logs show authentication events
- Frontend console shows token errors
- Network tab reveals API response codes
3. **Check browser console**:
- Look for authentication errors in browser console
- Check network tab for failed token requests
3. **Database inspection**:
- Check user table for account status
- Verify email verification status
- Review refresh token validity
4. **Email testing**:
- Use Mailpit at http://localhost:8025
- Check email templates and delivery
- Verify verification link generation
### Security Monitoring
- **Failed Login Attempts**: Monitor for brute force attacks
- **Token Abuse**: Detect unusual token usage patterns
- **Account Enumeration**: Prevent email/username discovery
- **Rate Limiting**: Implement request rate limiting for auth endpoints

34
Backend-Testing.md Normal file

@ -0,0 +1,34 @@
# Backend Testing
This page provides guidelines and best practices for testing the backend components of the Casino application.
## Unit Testing
Unit tests focus on testing individual components in isolation. Each class, function, or module should have corresponding unit tests.
## Integration Testing
For integration testing between backend components, see the [Integration-Testing](Integration-Testing) page.
## Mock Services
When testing services that interact with external APIs or databases, use mock implementations to isolate tests.
## Test Coverage
Aim for at least 80% code coverage for all backend components.
## Running Tests
```bash
# To run all tests
./gradlew test
# To run specific tests
./gradlew test --tests "com.casino.package.TestClass"
```
## Related Pages
- [Testing-Guidelines](Testing-Guidelines)
- [Integration-Testing](Integration-Testing)

371
Backend.md

@ -4,12 +4,14 @@ 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
- **Framework**: Spring Boot 3.5.0 with Java 23
- **Database**: PostgreSQL 17.5 with JPA/Hibernate
- **Authentication**: Custom JWT implementation + OAuth2 (GitHub, Google)
- **Build Tool**: Gradle with Kotlin DSL
- **API Documentation**: SpringDoc OpenAPI (Swagger)
- **Payment Processing**: Stripe API with webhook support
- **Email**: Spring Mail with Mailpit for development
- **Code Quality**: Checkstyle integration
## Project Structure
@ -19,58 +21,129 @@ 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
│ │ └── casino/
│ │ ├── CasinoApplication.java
│ │ ├── auth/
│ │ │ ├── AuthController.java
│ │ │ ├── JwtUtil.java
│ │ │ ├── OAuth2Service.java
│ │ │ └── SecurityConfig.java
│ │ ├── balance/
│ │ │ ├── BalanceController.java
│ │ │ └── BalanceService.java
│ │ ├── blackjack/
│ │ │ ├── BlackjackController.java
│ │ │ ├── BlackjackService.java
│ │ │ └── entities/
│ │ ├── coinflip/
│ │ │ ├── CoinflipController.java
│ │ │ └── CoinflipService.java
│ │ ├── config/
│ │ │ ├── CorsConfig.java
│ │ │ └── OpenApiConfig.java
│ │ ├── dice/
│ │ │ ├── DiceController.java
│ │ │ └── DiceService.java
│ │ ├── deposit/
│ │ │ ├── DepositController.java
│ │ │ └── DepositService.java
│ │ ├── email/
│ │ │ ├── EmailController.java
│ │ │ └── EmailService.java
│ │ ├── exception/
│ │ │ └── GlobalExceptionHandler.java
│ │ ├── lootbox/
│ │ │ ├── LootboxController.java
│ │ │ └── LootboxService.java
│ │ ├── shared/
│ │ │ ├── BettingService.java
│ │ │ ├── RandomizationService.java
│ │ │ └── entities/
│ │ ├── slots/
│ │ │ ├── SlotsController.java
│ │ │ └── SlotsService.java
│ │ ├── transaction/
│ │ │ ├── TransactionController.java
│ │ │ ├── TransactionService.java
│ │ │ └── TransactionEntity.java
│ │ └── user/
│ │ ├── UserController.java
│ │ ├── UserEntity.java
│ │ ├── UserRepository.java
│ │ └── UserService.java
│ └── resources/
│ └── application.properties
│ ├── application.properties
│ └── templates/
│ └── email/
└── test/
└── java/
└── de/
└── szut/
└── casino/
├── Lf8StarterApplicationTests.java
├── health/
│ └── HealthControllerTest.java
└── user/
└── UserControllerTest.java
└── casino/
├── balance/
│ └── BalanceServiceTest.java
├── coinflip/
│ └── CoinflipServiceTest.java
└── dice/
└── DiceServiceTest.java
```
## Key Modules
### User Management
### Game Modules
The user module handles:
#### Blackjack
Full-featured blackjack implementation with:
- Standard casino rules (hit, stand, double down, split)
- Dealer AI logic
- Card deck management
- Betting system integration
#### Coinflip
Simple heads/tails betting game with:
- 50/50 probability outcomes
- Configurable multipliers
- Instant results
#### Dice
Dice rolling game featuring:
- Configurable number of dice
- Various betting options
- Statistical outcome tracking
#### Slots
Slot machine implementation with:
- Multiple symbol types
- Payline calculations
- Configurable payout tables
- Bonus features
#### Lootbox
Virtual lootbox system with:
- Tier-based reward distribution
- Randomized item generation
- Rarity system
### Core Services
#### Authentication System
Comprehensive authentication handling:
- Custom JWT token generation and validation
- OAuth2 integration (GitHub, Google)
- User registration and email verification
- Password recovery flow
- Session management
Key components:
- `AuthController`: Authentication endpoints
- `JwtUtil`: JWT token utilities
- `OAuth2Service`: Social login integration
- `SecurityConfig`: Security configuration
#### User Management
Complete user lifecycle management:
- User registration and profile management
- Balance tracking
- User data retrieval and updates
- Balance tracking and updates
- Transaction history
- Account verification
Key components:
- `UserController`: REST endpoints for user operations
@ -78,78 +151,194 @@ Key components:
- `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
#### Transaction System
Robust transaction handling:
- Betting transaction processing
- Win/loss calculations
- Transaction history tracking
- Balance reconciliation
Key components:
- `DepositController`: REST endpoints for deposit operations
- `AmountDto`: Data transfer object for deposit amounts
- `SessionIdDto`: Data transfer object for Stripe session IDs
- `TransactionController`: Transaction endpoints
- `TransactionService`: Transaction business logic
- `TransactionEntity`: Transaction data model
- `BettingService`: Shared betting logic
### Security
The security module handles authentication and authorization:
- Integration with Keycloak for identity management
- JWT token validation
- Role-based access control
- Logout handling
#### Payment Processing
Stripe-integrated payment system:
- Deposit session creation
- Webhook handling for payment confirmation
- Balance updates
- Payment verification
Key components:
- `KeycloakSecurityConfig`: Configuration for Keycloak integration
- `KeycloakLogoutHandler`: Handles user logout flow
- `DepositController`: Payment endpoints
- `DepositService`: Payment processing logic
#### Email System
Comprehensive email functionality:
- Email verification
- Password recovery
- HTML email templates
- Development email testing with Mailpit
Key components:
- `EmailController`: Email operation endpoints
- `EmailService`: Email sending logic
### Shared Services
#### Balance Management
Centralized balance operations:
- Balance updates with atomic transactions
- Insufficient funds validation
- Balance history tracking
#### Randomization Service
Cryptographically secure randomization:
- Game outcome generation
- Auditable random number generation
- Configurable probability distributions
### Exception Handling
Global exception handling for consistent error responses:
- `GlobalExceptionHandler`: Central exception handler
- `ErrorDetails`: Standardized error response format
- `ResourceNotFoundException`: Custom exception for missing resources
- Standardized error response format
- Custom business logic exceptions
## API Endpoints
The backend exposes the following main API endpoints:
### Authentication API
- `POST /api/auth/register`: User registration
- `POST /api/auth/login`: User login
- `POST /api/auth/logout`: User logout
- `POST /api/auth/refresh`: Refresh JWT token
- `GET /api/auth/oauth2/{provider}`: OAuth2 social login
- `POST /api/auth/verify-email`: Email verification
- `POST /api/auth/forgot-password`: Password recovery
- `POST /api/auth/reset-password`: Password reset
### 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
- `GET /api/users/me`: Get current authenticated user
- `PUT /api/users/me`: Update user profile
- `GET /api/users/{id}/balance`: Get user balance
### Game APIs
#### Blackjack
- `POST /api/blackjack/start`: Start new blackjack game
- `POST /api/blackjack/hit`: Hit action
- `POST /api/blackjack/stand`: Stand action
- `POST /api/blackjack/double`: Double down
- `POST /api/blackjack/split`: Split cards
#### Coinflip
- `POST /api/coinflip/flip`: Execute coinflip bet
#### Dice
- `POST /api/dice/roll`: Execute dice roll bet
#### Slots
- `POST /api/slots/spin`: Execute slot machine spin
#### Lootbox
- `GET /api/lootbox/types`: Get available lootbox types
- `POST /api/lootbox/open`: Open a lootbox
### Transaction API
- `GET /api/transactions`: Get user transaction history
- `GET /api/transactions/{id}`: Get specific transaction
### Balance API
- `GET /api/balance`: Get current balance
- `POST /api/balance/add`: Add to balance (admin)
- `POST /api/balance/subtract`: Subtract from balance (admin)
### Deposit API
- `POST /api/deposits/create-session`: Create a Stripe payment session
- `POST /api/deposits/verify`: Verify a completed payment
- `POST /api/deposits/create-session`: Create Stripe payment session
- `POST /api/deposits/webhook`: Stripe webhook handler
- `GET /api/deposits/history`: Get deposit history
### Health API
### Email API
- `GET /api/health`: Health check endpoint
- `POST /api/email/send-verification`: Send verification email
- `POST /api/email/resend-verification`: Resend verification email
## 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
### JWT Authentication
1. User registers or logs in through the application
2. Backend generates JWT access and refresh tokens
3. Frontend stores tokens and includes access token in API requests
4. Backend validates JWT tokens for protected endpoints
5. User info is extracted from validated tokens
6. Refresh tokens are used to obtain new access tokens
### OAuth2 Social Login
1. User clicks social login (GitHub/Google)
2. User is redirected to OAuth2 provider
3. After authorization, user is redirected back with auth code
4. Backend exchanges auth code for user information
5. User account is created or linked
6. JWT tokens are generated for the session
### Email Verification
1. User registers with email address
2. Verification email is sent with unique token
3. User clicks verification link
4. Backend validates token and activates account
5. User can now fully access the platform
## 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 |
| Column | Type | Description |
|------------------|-------------|-----------------------------------|
| id | BIGINT | Primary key |
| username | VARCHAR | User's username |
| email | VARCHAR | User's email address |
| password_hash | VARCHAR | Hashed password |
| balance | DECIMAL | User's virtual currency balance |
| email_verified | BOOLEAN | Email verification status |
| oauth2_provider | VARCHAR | OAuth2 provider (if applicable) |
| oauth2_id | VARCHAR | OAuth2 user ID |
| created_at | TIMESTAMP | Account creation timestamp |
| updated_at | TIMESTAMP | Last update timestamp |
### Transaction Table
| Column | Type | Description |
|--------------|-------------|-----------------------------------|
| id | BIGINT | Primary key |
| user_id | BIGINT | Foreign key to user |
| type | VARCHAR | Transaction type (BET, WIN, etc.) |
| amount | DECIMAL | Transaction amount |
| game_type | VARCHAR | Game associated with transaction |
| description | VARCHAR | Transaction description |
| created_at | TIMESTAMP | Transaction timestamp |
### Blackjack Game Session Table
| Column | Type | Description |
|------------------|-------------|-----------------------------------|
| id | BIGINT | Primary key |
| user_id | BIGINT | Foreign key to user |
| bet_amount | DECIMAL | Bet amount for the game |
| player_hand | TEXT | JSON representation of player hand|
| dealer_hand | TEXT | JSON representation of dealer hand|
| game_status | VARCHAR | Current game status |
| result | VARCHAR | Game result (WIN, LOSE, PUSH) |
| created_at | TIMESTAMP | Game creation timestamp |
| updated_at | TIMESTAMP | Last update timestamp |
## Development Workflow

64
Deployment-Guide.md Normal file

@ -0,0 +1,64 @@
# Deployment Guide
This page provides detailed instructions for deploying the Casino application to various environments.
## Prerequisites
- Docker and Docker Compose
- Access credentials for the deployment environment
- SSL certificates (for production)
## Development Environment
For local development deployment, see [Development-Environment-Setup](Development-Environment-Setup).
## Staging Environment
```bash
# Deploy to staging
./deploy.sh staging
```
## Production Environment
```bash
# Deploy to production
./deploy.sh production
```
## Docker Deployment
The application is containerized using Docker. The main components are:
1. Frontend (Angular)
2. Backend (Spring Boot)
3. Keycloak (Authentication)
4. PostgreSQL (Database)
See the docker-compose files in the `/docker` directory for the complete setup.
## Monitoring
After deployment, verify that all services are running properly:
```bash
# Check container status
docker ps
# View logs
docker-compose logs -f
```
## Rollback Procedure
In case of deployment issues:
```bash
# Rollback to previous version
./deploy.sh rollback
```
## Related Pages
- [Development-Environment-Setup](Development-Environment-Setup)
- [Troubleshooting](Troubleshooting)

63
External-Services.md Normal file

@ -0,0 +1,63 @@
# External Services
This page documents the external services and APIs integrated with the Casino application.
## Payment Processors
### Stripe
The application integrates with Stripe for payment processing.
- API Version: 2023-10-16
- Documentation: [Stripe API Docs](https://stripe.com/docs/api)
- Implementation: See [Payment-System](Payment-System) for details
### PayPal
Alternative payment processing through PayPal.
- API Version: v2
- Documentation: [PayPal Developer](https://developer.paypal.com/docs/api/overview/)
## Authentication
### Keycloak
Keycloak handles authentication and authorization.
- Version: 21.1
- Configuration: See [Authentication-and-Authorization](Authentication-and-Authorization)
## Game Providers
### Slot Provider API
- Endpoint: `https://api.slotprovider.com/v1`
- Integration: See [Game-Modules](Game-Modules) for details
### Table Games API
- Endpoint: `https://api.tablegames.com/v2`
- Integration: See [Game-Modules](Game-Modules) for details
## Monitoring
### Prometheus
- Endpoint: `http://prometheus:9090`
- Metrics exposed at `http://backend:8080/actuator/prometheus`
### Grafana
- Dashboard: `http://grafana:3000`
- Default dashboards for application monitoring
## Configuration
External service credentials are managed through environment variables. See the docker-compose files for reference.
## Related Pages
- [API-Documentation](API-Documentation)
- [Payment-System](Payment-System)
- [Authentication-and-Authorization](Authentication-and-Authorization)

86
Frontend-Testing.md Normal file

@ -0,0 +1,86 @@
# Frontend Testing
This page provides guidelines and best practices for testing the Angular frontend of the Casino application.
## Unit Testing
Unit tests for Angular components, services, and pipes are written using Jasmine and Karma.
### Running Unit Tests
```bash
# Run all unit tests
npm run test
# Run tests with coverage
npm run test:coverage
```
## Component Testing
Component tests verify that components render correctly and respond to user interactions as expected.
```typescript
describe('GameComponent', () => {
let component: GameComponent;
let fixture: ComponentFixture<GameComponent>;
beforeEach(async () => {
await TestBed.configureTestingModule({
declarations: [GameComponent]
}).compileComponents();
});
beforeEach(() => {
fixture = TestBed.createComponent(GameComponent);
component = fixture.componentInstance;
fixture.detectChanges();
});
it('should create', () => {
expect(component).toBeTruthy();
});
});
```
## End-to-End Testing
E2E tests are written using Cypress to test the application as a whole.
### Running E2E Tests
```bash
# Open Cypress test runner
npm run e2e
# Run all E2E tests headlessly
npm run e2e:ci
```
## Mocking Services
Use Angular's `HttpClientTestingModule` to mock HTTP requests:
```typescript
TestBed.configureTestingModule({
imports: [HttpClientTestingModule],
providers: [GameService]
});
```
## Test Coverage
Aim for at least 80% code coverage for all frontend components.
## Best Practices
1. Test component outputs and inputs
2. Mock external services
3. Test form validation
4. Verify component state changes
5. Test error handling
## Related Pages
- [Testing-Guidelines](Testing-Guidelines)
- [Frontend](Frontend)

67
Frontend.md

@ -128,33 +128,68 @@ The application uses a consistent set of UI components:
## Development Workflow
1. Start the development server with proxy configuration
1. Install dependencies:
```bash
bun install
```
2. Start the development server with proxy configuration:
```bash
bun run start
```
or
```bash
bunx @angular/cli serve --proxy-config src/proxy.conf.json
```
This runs: `bunx @angular/cli serve --proxy-config src/proxy.conf.json`
2. The application will be available at http://localhost:4200
3. The application will be available at http://localhost:4200
3. API calls are proxied to the backend service running on http://localhost:8080
4. API calls are proxied to the backend service running on http://localhost:8080
4. For formatting code:
5. For code formatting:
```bash
bun run format
```
or
```bash
prettier --write "src/**/*.{ts,html,css,scss}"
```
This runs: `prettier --write "src/**/*.{ts,html,css,scss}"`
5. For linting:
6. For linting:
```bash
bun run lint
```
or
This runs: `ng lint`
7. For building the application:
```bash
ng lint
```
bun run build
```
This creates an optimized production build
8. For running tests:
```bash
bun run test
```
This runs the Jasmine/Karma test suite
## Environment Configuration
The application uses environment files for configuration:
- `environment.ts`: Development configuration
- `environment.prod.ts`: Production configuration
Key configuration options:
- `apiUrl`: Backend API base URL
- `stripePublishableKey`: Stripe public key
- `oauth2Config`: OAuth2 provider settings
## Proxy Configuration
The `proxy.conf.json` file configures API proxying for development:
```json
{
"/api/*": {
"target": "http://localhost:8080",
"secure": false,
"changeOrigin": true,
"logLevel": "debug"
}
}
```

378
Game-Modules.md

@ -8,120 +8,121 @@ The Casino Gaming Platform offers a variety of casino-style games, each implemen
## Available Games
### Poker
![Poker](/public/poker.webp)
A classic card game where players bet on the strength of their hands.
**Features:**
- Texas Hold'em variant
- Single player against AI opponents
- Multiple difficulty levels
- Realistic betting system
- Hand strength evaluator
- Game history tracking
**Technical Implementation:**
- Angular component-based UI
- Canvas-based card animation
- WebSocket connectivity for future multiplayer support
- AI logic implemented with configurable strategies
### Blackjack
![Blackjack](/public/blackjack.webp)
Also known as 21, players compete against the dealer to get closest to 21 without going over.
A classic card game where players compete against the dealer to get closest to 21 without going over.
**Features:**
- Standard casino rules
- Betting system with chips
- Split, double down, and insurance options
- Detailed statistics tracking
- Adaptive dealer AI
- Standard casino rules (hit, stand, double down, split)
- Real-time betting system with balance integration
- Professional dealer AI logic
- Card animation and visual effects
- Comprehensive game state management
- Transaction tracking for wins and losses
**Technical Implementation:**
- SVG-based card rendering
- State-based game progression
- Configurable rule variations
- Strategy hints system
- Angular component with TypeScript game logic
- Card deck management with proper shuffling
- State-based game progression (betting, dealing, playing, resolution)
- RESTful API integration for game actions
- Real-time balance updates
- Responsive design for mobile and desktop
**API Endpoints:**
- `POST /api/blackjack/start`: Initialize new game session
- `POST /api/blackjack/hit`: Hit action
- `POST /api/blackjack/stand`: Stand action
- `POST /api/blackjack/double`: Double down
- `POST /api/blackjack/split`: Split cards
### Coinflip
A simple heads or tails betting game with 50/50 odds.
**Features:**
- Simple heads/tails selection
- Configurable bet amounts
- Instant result revelation
- Animated coin flip with sound effects
- 2x multiplier on wins
- Transaction history integration
**Technical Implementation:**
- Lightweight Angular component
- CSS animations for coin flip effect
- Audio service integration for sound effects
- Secure random number generation on backend
- Real-time balance updates
**API Endpoints:**
- `POST /api/coinflip/flip`: Execute coinflip bet
### Dice
A dice rolling game with configurable betting options.
**Features:**
- Multiple dice configuration options
- Various betting strategies
- Animated dice rolling effects
- Statistical outcome tracking
- Configurable payout multipliers
- Sound effects and visual feedback
**Technical Implementation:**
- Angular component with dice animation
- Flexible betting system
- Backend randomization service
- Transaction processing
- Responsive UI design
**API Endpoints:**
- `POST /api/dice/roll`: Execute dice roll bet
### Slots
![Slots](/public/slots.webp)
A virtual slot machine with various themes and payout structures.
A virtual slot machine with symbol-based payouts.
**Features:**
- Multiple slot machine themes
- Variable paylines
- Bonus games and free spins
- Progressive jackpots
- Animated winning combinations
- Multiple symbol types with different values
- Animated reel spinning effects
- Payline calculation system
- Configurable payout tables
- Sound effects and visual celebrations
- Progressive betting options
**Technical Implementation:**
- CSS animation for reel spinning
- WebGL effects for special features
- Pseudo-random number generation with auditable results
- Configurable payout tables
- Symbol combination logic
- Payout calculation engine
- Audio integration for immersive experience
- Responsive design for various screen sizes
### Plinko
![Plinko](/public/plinko.webp)
A game where a ball drops through a field of pegs into prize slots.
**Features:**
- Realistic physics simulation
- Adjustable risk levels
- Multiple ball options
- Visual path tracking
- Slow-motion replays
**Technical Implementation:**
- Physics engine for realistic ball movement
- Canvas-based rendering
- Adjustable difficulty parameters
- Verifiable random drop patterns
### Liars Dice
![Liars Dice](/public/liars-dice.webp)
A bluffing dice game where players make increasingly higher bids about the dice in play.
**Features:**
- Single player against AI opponents
- Traditional rules with customizable variations
- Opponent personality types
- Bluff detection AI
- Detailed game history
**Technical Implementation:**
- 3D dice rendering
- Probability-based AI decision making
- Adaptive opponent difficulty
- Social features for future multiplayer support
**API Endpoints:**
- `POST /api/slots/spin`: Execute slot machine spin
### Lootboxes
![Lootboxes](/public/lootbox.webp)
A collection of virtual lootboxes with random in-game rewards.
Virtual lootboxes with randomized rewards and rarity system.
**Features:**
- Multiple box tiers and themes
- Animated unboxing experience
- Collection tracking
- Rare item showcase
- Trading system (planned)
- Multiple lootbox tiers and types
- Animated opening experience
- Rarity-based reward distribution
- Collection and inventory tracking
- Visual reward reveals
- Purchase system integration
**Technical Implementation:**
- 3D box models with WebGL rendering
- Probability-based reward distribution
- Account-linked inventory system
- Social sharing of rare acquisitions
- Angular component with opening animations
- Probability-based reward generation
- Database inventory system
- Visual effects for rare items
- Integration with user balance system
**API Endpoints:**
- `GET /api/lootbox/types`: Get available lootbox types
- `POST /api/lootbox/open`: Open a lootbox
## Game Architecture
@ -179,26 +180,38 @@ To add a new game to the platform:
### Game Development Guidelines
1. **Fairness**:
- All games must use the platform's verifiable RNG
- Game odds must be transparent and documented
- House edge must be clearly defined
1. **Fairness and Security**:
- All games use server-side randomization service
- Game odds are transparent and mathematically verified
- House edge is clearly documented
- All transactions are atomic and auditable
2. **User Experience**:
- Consistent UI patterns across games
- Clear instructions and help documentation
- Responsive design for all device types
- Accessibility compliance (WCAG 2.1 AA)
- Consistent UI patterns using shared Angular components
- TailwindCSS for consistent styling
- Responsive design for mobile and desktop
- Audio feedback and visual effects
- Clear game instructions and rules
3. **Performance**:
- Games should initialize in under 3 seconds
- Animations should maintain 60fps
- Games should gracefully degrade on lower-end devices
3. **Performance Standards**:
- Games initialize in under 2 seconds
- Animations maintain 60fps on target devices
- Optimized bundle sizes
- Lazy loading for game modules
4. **State Management**:
- Games must handle disconnections gracefully
- Game state should be recoverable
- Critical operations must be atomic
4. **Technical Requirements**:
- TypeScript strict mode compliance
- Comprehensive error handling
- Real-time balance updates
- Transaction rollback capabilities
- Cross-browser compatibility
5. **Code Quality**:
- ESLint and Prettier formatting
- Checkstyle compliance (backend)
- Unit test coverage requirements
- Code review mandatory
- Documentation standards
## Transaction Flow
@ -219,7 +232,22 @@ All game transactions:
- Are cryptographically signed
- Can be audited by administrators
## Testing and Validation
## Testing and Quality Assurance
### Current Testing Coverage
Implemented tests for core game functionality:
#### Backend Testing
- **Balance Service Tests**: Atomic transaction testing
- **Coinflip Service Tests**: Randomization and payout validation
- **Dice Service Tests**: Game logic and outcome verification
- **User Service Tests**: Authentication and profile management
#### Frontend Testing
- **Component Unit Tests**: Jasmine/Karma test suite
- **Service Integration Tests**: API interaction testing
- **UI/UX Testing**: Manual testing across devices
### Game Testing Requirements
@ -228,41 +256,125 @@ All games must include:
2. **Integration tests** for frontend-backend interactions
3. **Performance tests** for animation and rendering
4. **Fairness tests** verifying expected return to player (RTP)
5. **Usability tests** with representative users
5. **Security tests** for exploit prevention
### Validation Process
### Quality Assurance Process
Before release, each game undergoes:
1. Code review by senior developers
2. Mathematical verification of odds
3. Security audit for potential exploits
4. Accessibility evaluation
5. Performance profiling on target devices
1. Automated test suite execution
2. Code review by development team
3. Mathematical verification of odds and payouts
4. Security audit for potential vulnerabilities
5. Cross-browser and device compatibility testing
6. Performance profiling and optimization
## Game Architecture
### Shared Game Infrastructure
All games share common infrastructure components:
#### Balance Management
- Centralized balance service
- Atomic transaction processing
- Real-time balance updates
- Insufficient funds validation
#### Audio System
- Game-specific sound effects
- Background music support
- Volume controls
- Browser audio API integration
#### Transaction Processing
- Comprehensive transaction logging
- Win/loss calculation
- Historical tracking
- Audit trail maintenance
#### Security Features
- Server-side randomization
- Bet validation
- Balance verification
- Anti-cheat measures
### Game Development Pattern
Each game follows a consistent development pattern:
1. **Frontend Component**:
- Game UI and animations
- User input handling
- State management
- API integration
2. **Backend Service**:
- Game logic implementation
- Random number generation
- Result calculation
- Transaction processing
3. **Database Integration**:
- Game session tracking
- Transaction recording
- User statistics
- Audit logging
## Future Game Roadmap
Planned additions to the game library:
1. **Roulette**: European and American variants
2. **Craps**: Full-featured dice game
3. **Baccarat**: Card game with simple betting
4. **Video Poker**: Multiple variants
5. **Multiplayer Poker**: Real-time tables with multiple players
1. **Poker**: Texas Hold'em implementation
2. **Roulette**: European and American variants
3. **Craps**: Full-featured dice game
4. **Baccarat**: Card game with banker/player betting
5. **Video Poker**: Jacks or Better and variants
6. **Multiplayer Features**: Real-time multiplayer games
7. **Tournament Mode**: Competitive gaming events
## Development Tools and Build Process
### Build System
- **Frontend**: Angular CLI with Bun package manager
- **Backend**: Gradle with Kotlin DSL
- **Code Quality**: ESLint, Prettier, Checkstyle
- **Testing**: Jasmine/Karma (frontend), JUnit 5 (backend)
### Development Workflow
1. Feature development in isolated branches
2. Automated testing with every commit
3. Code review and quality checks
4. Integration testing
5. Deployment through CI/CD pipeline
### Performance Monitoring
- Game performance metrics
- User engagement analytics
- Error tracking and logging
- Real-time system monitoring
## Support and Maintenance
### Game Updates
### Continuous Integration
Games receive regular updates for:
- Bug fixes
- Performance improvements
- New features and content
- Seasonal themes and events
- Automated testing on pull requests
- Code quality enforcement
- Security vulnerability scanning
- Performance regression testing
### Support Process
### Release Management
For issues with specific games:
1. Users report issues through the in-game support interface
2. Support tickets are categorized by game and issue type
3. Development team prioritizes fixes based on impact
4. Updates are deployed in the next release cycle
- Semantic versioning
- Automated release notes
- Rollback capabilities
- Feature flag management
### Monitoring and Analytics
- Game session tracking
- User behavior analytics
- Performance metrics
- Error rate monitoring

87
Git-Workflow.md Normal file

@ -0,0 +1,87 @@
# Git Workflow
This page outlines the Git workflow used for the Casino project.
## Branching Strategy
We follow a modified Git Flow strategy:
- `main`: Production-ready code
- `develop`: Integration branch for features
- `feature/*`: Feature branches
- `bugfix/*`: Bug fix branches
- `release/*`: Release preparation branches
- `hotfix/*`: Urgent fixes for production
## Creating a New Feature
```bash
# Start from develop branch
git checkout develop
git pull
# Create a new feature branch
git checkout -b feature/new-feature-name
```
## Commit Guidelines
Follow conventional commits pattern:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code
- refactor: Code change that neither fixes a bug nor adds a feature
- test: Adding or modifying tests
- chore: Changes to the build process or auxiliary tools
Example:
```
feat(auth): add keycloak integration
Implements Keycloak authentication for user management.
Closes #123
```
## Pull Requests
1. Push your branch to the remote repository
2. Create a pull request to the `develop` branch
3. Request reviews from at least two team members
4. Address review comments
5. Merge only when all checks pass
## Code Review Checklist
- Does the code follow our [Coding-Standards](Coding-Standards)?
- Are there sufficient tests?
- Is the documentation updated?
- Do all CI checks pass?
- Does the implementation match the requirements?
## Merge Strategy
We use squash merging for feature branches to keep the history clean:
```bash
# Squash merge a feature branch to develop
git checkout develop
git merge --squash feature/new-feature
git commit -m "feat(component): add new feature"
```
## Related Pages
- [Coding-Standards](Coding-Standards)
- [Development-Environment-Setup](Development-Environment-Setup)

90
Glossary.md Normal file

@ -0,0 +1,90 @@
# Glossary
This page provides definitions for common terms used throughout the Casino application.
## A
### Authentication
The process of verifying the identity of a user, typically through username/password or other credentials.
### Authorization
The process of determining what actions a user is allowed to perform after they are authenticated.
## B
### Backend
The server-side components of the application that handle business logic, data storage, and API endpoints.
### Bet
A wager placed by a user on a game with an uncertain outcome.
## C
### Casino Chip
Virtual currency used within the platform for placing bets and receiving winnings.
### CI/CD
Continuous Integration/Continuous Deployment - automated processes for testing and deploying code changes.
## D
### Docker
A platform used to develop, ship, and run applications inside containers.
### DTO (Data Transfer Object)
Objects used to transfer data between subsystems of the application.
## F
### Frontend
The client-side components of the application that users interact with directly in their browsers.
## G
### Game Module
A self-contained component that implements a specific casino game (slots, poker, etc.).
### GGR (Gross Gaming Revenue)
The difference between the amount of money players wager minus the amount that they win.
## J
### JWT (JSON Web Token)
A compact, URL-safe means of representing claims to be transferred between two parties.
## K
### Keycloak
An open source identity and access management solution used for authentication.
## P
### Payment Processor
A third-party service that handles financial transactions between users and the platform.
### Progressive Jackpot
A jackpot that increases incrementally as players make bets.
## R
### RNG (Random Number Generator)
A system used to generate a sequence of numbers that cannot be reasonably predicted.
### RTP (Return to Player)
The percentage of wagered money that a game returns to players over time.
## S
### Session
A period of continuous user activity on the platform.
## W
### Wallet
A virtual account that holds a user's funds within the platform.
## Related Pages
- [API-Documentation](API-Documentation)
- [Game-Modules](Game-Modules)
- [Payment-System](Payment-System)

42
Home.md

@ -4,36 +4,41 @@ Welcome to the Casino Gaming Platform wiki. This comprehensive guide provides do
## 🎮 Project Overview
The Casino Gaming Platform is an online gaming system offering various casino-style games with virtual currency support. The platform features a modern tech stack with Angular frontend, Spring Boot backend, and complete user authentication via Keycloak.
The Casino Gaming Platform is an online gaming system offering various casino-style games with virtual currency support. The platform features a modern tech stack with Angular 20 frontend, Spring Boot 3.5 backend with Java 23, and hybrid authentication system using JWT tokens and OAuth2 integration.
### Features
- Multiple casino games: Poker, Blackjack, Slots, Plinko, Liars Dice, and Lootboxes
- User authentication and account management via Keycloak
- Multiple casino games: Blackjack, Coinflip, Dice, Slots, and Lootboxes
- User authentication with JWT tokens and OAuth2 (GitHub, Google)
- Virtual currency deposit system using Stripe payments
- Transaction history tracking
- Responsive modern UI built with Angular and TailwindCSS
- Transaction history tracking with complete audit trail
- Audio system with sound effects for immersive gameplay
- Responsive modern UI built with Angular 20 and TailwindCSS v4
- Email verification and password recovery system
## 🏗️ Technical Architecture
### Frontend (Angular)
### Frontend (Angular 20)
The frontend is built with Angular 18, providing a responsive and modern user interface for the casino gaming experience. It uses:
The frontend is built with Angular 20 (latest), providing a responsive and modern user interface for the casino gaming experience. It uses:
- **TailwindCSS** for styling and consistent design patterns
- **Keycloak Integration** for authentication
- **Stripe Payment Integration** for virtual currency deposits
- **Modal Animation Service** for consistent UI transitions
- **TailwindCSS v4.0.3** for styling and consistent design patterns
- **JWT Authentication** with OAuth2 social login support
- **Stripe.js Integration** for virtual currency deposits
- **GSAP & CountUp.js** for animations and enhanced UX
- **FontAwesome** for icons and visual elements
[Frontend Documentation](Frontend)
### Backend (Spring Boot)
### Backend (Spring Boot 3.5)
The backend is built on Spring Boot (Java), providing robust API endpoints for game functionality, user management, and transaction processing. Key components include:
The backend is built on Spring Boot 3.5 with Java 23, providing robust API endpoints for game functionality, user management, and transaction processing. Key components include:
- **PostgreSQL Database** for data persistence
- **Keycloak Integration** for authentication/authorization
- **Stripe API** for payment processing
- **PostgreSQL 17.5** for data persistence with JPA/Hibernate
- **JWT Authentication** with custom implementation + OAuth2 providers
- **Stripe API** for payment processing with webhook support
- **SpringDoc OpenAPI** for comprehensive API documentation
- **Spring Mail** with Mailpit for development email testing
[Backend Documentation](Backend)
@ -41,8 +46,9 @@ The backend is built on Spring Boot (Java), providing robust API endpoints for g
The entire application stack is containerized using Docker, making deployment and scaling straightforward. The infrastructure includes:
- **PostgreSQL Databases** (application and Keycloak)
- **Keycloak Authentication Server**
- **PostgreSQL Database** with persistent volumes
- **Mailpit Email Server** for development email testing
- **Gradle Build System** with Kotlin DSL and Checkstyle integration
## 🚀 Getting Started

125
Integration-Testing.md Normal file

@ -0,0 +1,125 @@
# Integration Testing
This page covers the integration testing strategy for the Casino application.
## Overview
Integration tests verify that different components of the system work together correctly. They test the interaction between:
- Backend services
- Database access
- External APIs
- Frontend components (where applicable)
## Backend Integration Tests
Backend integration tests focus on testing the interaction between multiple backend components and external services.
### Spring Boot Integration Tests
```java
@SpringBootTest
@AutoConfigureMockMvc
public class GameServiceIntegrationTest {
@Autowired
private MockMvc mockMvc;
@MockBean
private ExternalGameProvider externalGameProvider;
@Test
public void testCreateGame() throws Exception {
// Arrange
when(externalGameProvider.initialize()).thenReturn(true);
// Act & Assert
mockMvc.perform(post("/api/games")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"gameType\":\"SLOTS\",\"betAmount\":10}"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.gameId").exists());
}
}
```
## End-to-End Testing
E2E tests simulate real user scenarios across the entire application stack.
### Running E2E Tests
```bash
# Backend and frontend E2E tests
./gradlew e2eTest
```
## Database Integration
Tests involving database operations:
```java
@DataJpaTest
public class UserRepositoryTest {
@Autowired
private UserRepository userRepository;
@Test
public void testFindByUsername() {
// Arrange
User user = new User();
user.setUsername("testuser");
user.setEmail("test@example.com");
userRepository.save(user);
// Act
User found = userRepository.findByUsername("testuser");
// Assert
assertNotNull(found);
assertEquals("test@example.com", found.getEmail());
}
}
```
## API Contract Testing
Using Spring Cloud Contract to ensure API compatibility:
```groovy
Contract.make {
description "Should return a user by ID"
request {
method GET()
url "/api/users/1"
}
response {
status 200
headers {
contentType applicationJson()
}
body([
"id": 1,
"username": "testuser",
"email": "test@example.com"
])
}
}
```
## Test Data Management
Integration tests should:
1. Set up their own test data
2. Clean up after test execution
3. Be independent and idempotent
## Related Pages
- [Backend-Testing](Backend-Testing)
- [Frontend-Testing](Frontend-Testing)
- [Testing-Guidelines](Testing-Guidelines)