Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ccasro/hub/llms.txt

Use this file to discover all available pages before exploring further.

The Hub backend is built using hexagonal architecture (Ports and Adapters) with clearly separated modules. Each module is organized into domain, application, and infrastructure layers.

​
Architecture Overview

The backend follows Domain-Driven Design (DDD) principles with hexagonal architecture:
  • Domain Layer: Contains business logic, entities, value objects, and domain ports
  • Application Layer: Orchestrates use cases and defines DTOs/commands
  • Infrastructure Layer: Implements adapters for persistence, APIs, and external services
All modules are located in backend/src/main/java/com/ccasro/hub/modules/

​
Core Technology Stack

Framework

Spring Boot 3.5.10

Language

Java 21

Database

PostgreSQL with PostGIS

ORM

Spring Data JPA + Hibernate Spatial

​
Module Structure

Each module follows a consistent structure: 
module-name/
├── domain/
│   ├── Entity.java                    # Aggregate roots
│   ├── valueobjects/                  # Value objects
│   ├── events/                        # Domain events
│   ├── exception/                     # Domain exceptions
│   └── ports/out/                     # Output ports (repositories, services)
├── application/
│   ├── dto/                           # Data transfer objects
│   └── port/out/                      # Application-specific read ports
├── usecases/
│   └── *Service.java                  # Use case implementations
└── infrastructure/
    ├── api/                           # REST controllers and DTOs
    ├── persistence/                   # JPA entities and repositories
    └── adapters/                      # External service adapters

​
Modules

​
Booking Module

Purpose: Manages court bookings and payment processingLocation: modules/booking/Domain Entities:
  • Booking - Core booking aggregate with lifecycle management
  • Payment - Payment tracking and status
Key Value Objects:
  • BookingId, PaymentId
  • BookingStatus - PENDING_PAYMENT, CONFIRMED, CANCELLED, PENDING_MATCH
  • PaymentStatus - PENDING, PAID, FAILED, REFUNDED
Domain Events:
  • BookingConfirmedEvent
  • BookingCancelledEvent
  • BookingExpiredEvent
Use Cases:
  • CreateBookingService - Create new bookings with payment holds
  • ConfirmBookingPaymentService - Confirm payment and activate booking
  • CancelBookingService - Handle user-initiated cancellations (24h rule)
  • AdminBookingService - Admin override for cancellations
  • ExpirePaymentHoldsJob - Background job to expire unpaid bookings
  • GetMyBookingsService - Retrieve user’s bookings
  • GetOwnerBookingsService - Retrieve owner’s venue bookings
Key Business Rules:
  • Bookings must be paid within hold duration (configurable)
  • Cancellations require 24 hours notice for refunds
  • Slot overlap prevention (enforced at database level)
  • Match bookings have different lifecycle (PENDING_MATCH status)
Output Ports:
  • BookingRepositoryPort - Booking persistence
  • PaymentRepositoryPort - Payment persistence
  • PaymentPort - External payment provider integration
  • ResourceValidationPort - Validate resource availability
  • BookingNotificationPort - Send booking notifications

​
Venue Module

Purpose: Manages padel venues owned by venue operatorsLocation: modules/venue/Domain Entities:
  • Venue - Venue aggregate with location and images
  • VenueImage - Venue photos with ordering
Key Value Objects:
  • VenueId, VenueName
  • Address - Street, city, country, postal code
  • Coordinates - Latitude/longitude for geographic queries
  • VenueStatus - PENDING_REVIEW, ACTIVE, REJECTED, SUSPENDED
Use Cases:
  • CreateVenueService - Register new venue (requires approval)
  • UpdateVenueService - Modify venue details
  • GetVenueService - Public venue details
  • GetMyVenuesService - Owner’s venue list
  • SearchVenuesService - Geographic and filter-based search
  • VenueImageService - Manage venue images
  • Admin approval/rejection workflows
Key Business Rules:
  • Venues require admin approval before going public
  • Only owners can modify their venues
  • Updates to active venues trigger re-review
  • Geographic search uses PostGIS
Output Ports:
  • VenueRepositoryPort - Venue persistence with geo queries

​
Resource Module

Purpose: Manages bookable resources (courts) within venuesLocation: modules/resource/Domain Entities:
  • Resource - Court/facility aggregate
  • DaySchedule - Operating hours per day of week
  • ResourceImage - Resource photos
Key Value Objects:
  • ResourceId, ResourceName
  • ResourceType - PADEL_COURT, TENNIS_COURT, etc.
  • ResourceStatus - PENDING_REVIEW, ACTIVE, REJECTED, SUSPENDED
  • SlotDuration - Booking slot length (e.g., 60, 90 minutes)
  • SlotRange - Start and end times for a booking slot
  • PriceRule - Dynamic pricing by day type and time range
  • DayType - WEEKDAY, WEEKEND, MONDAY, TUESDAY, etc.
  • DayOfWeek - Business enum for days
Use Cases:
  • CreateResourceService - Add new court to venue
  • UpdateResourceService - Modify resource details
  • GetResourceService - Public resource details
  • SearchResourcesService - Find available courts
  • GetAvailabilityService - Get available slots for a date
  • ManageScheduleService - Set opening/closing hours
  • ManagePricingService - Configure dynamic pricing rules
  • Admin approval workflows
Key Business Rules:
  • Resources belong to exactly one venue
  • Schedules define availability by day of week
  • Pricing rules support time-based and day-type variations
  • Slot generation based on schedule and duration
  • Resources require admin approval
Output Ports:
  • ResourceRepositoryPort - Resource persistence
  • BookedSlotsPort - Query booked time slots
  • SlotAvailabilityPort - Check slot availability
  • ResourceCountPort - Statistics queries

​
Matching Module

Purpose: Facilitates finding and organizing matches with other playersLocation: modules/matching/Domain Entities:
  • MatchRequest - Match organization aggregate
  • MatchPlayer - Player participation in match
  • MatchInvitation - Invitation to join match
Key Value Objects:
  • MatchRequestId, InvitationToken
  • MatchStatus - AWAITING_ORGANIZER_PAYMENT, OPEN, FULL, CANCELLED, EXPIRED
  • MatchFormat - SINGLES, DOUBLES (defines team structure)
  • MatchSkillLevel - BEGINNER, INTERMEDIATE, ADVANCED
  • PlayerRole - ORGANIZER, GUEST
  • PlayerTeam - TEAM_A, TEAM_B
  • GeoPoint - Search center coordinates
  • MatchInvitationStatus - PENDING, ACCEPTED, DECLINED
Domain Events:
  • MatchFullEvent - Triggered when match reaches capacity
  • MatchInvitationsEvent - Sent to eligible players
Use Cases:
  • CreateMatchRequestService - Organize new match
  • JoinMatchService - Join an open match
  • LeaveMatchService - Leave before match starts
  • CancelMatchService - Cancel match (organizer only)
  • InvitePlayersService - Send invitations to eligible players
  • RespondToInvitationService - Accept/decline invitation
  • CheckInService - Player check-in at venue
  • ReportAbsenceService - Report no-show player
  • FindEligiblePlayersService - Geographic and skill-based matching
  • ExpireMatchRequestsJob - Auto-expire old matches
Key Business Rules:
  • Organizer pays first, then match opens to players
  • Geographic radius search for nearby players
  • Skill level filtering for balanced matches
  • Team assignment (singles: all TEAM_A, doubles: A/B split)
  • Cooldown period between match creations
  • Max active matches per user
  • No-show tracking and banning system
  • Match closes 24 hours before start time
Exceptions:
  • MatchFullException, TeamFullException
  • PlayerAlreadyJoinedException
  • MatchCreationCooldownException
  • TooManyActiveMatchesException
  • PlayerMatchBannedException
  • PlayerTimeConflictException
Output Ports:
  • MatchRequestRepositoryPort - Match persistence
  • MatchInvitationRepositoryPort - Invitation tracking
  • EligiblePlayerPort - Find matching players by criteria
  • MatchNotificationPort - Send match notifications

​
IAM Module

Purpose: User profile management and authentication integrationLocation: modules/iam/Domain Entity:
  • UserProfile - User account and preferences
Key Value Objects:
  • Auth0Id - External identity provider ID
  • Email, DisplayName, PhoneNumber
  • SkillLevel - BEGINNER, INTERMEDIATE, ADVANCED
  • SportPreference - PADEL, TENNIS, SQUASH, BADMINTON
  • OwnerRequestStatus - NONE, PENDING, APPROVED, REJECTED
Use Cases:
  • GetOrCreateUserService - Sync with Auth0 on login
  • UpdateProfileService - Edit profile information
  • UploadAvatarService - Change profile picture
  • RequestOwnerRoleService - Request venue owner privileges
  • GetUserStatsService - Retrieve user statistics
  • Admin user management (approve owner requests, ban users)
Key Business Rules:
  • Users auto-created on first Auth0 login
  • Default role: PLAYER
  • Owner role requires admin approval
  • Onboarding completed when display name and city set
  • No-show tracking for match reliability
  • Temporary bans after 3 no-shows (30 days)
  • Match notification preferences
Output Ports:
  • UserProfileRepositoryPort - User persistence
  • UserStatsPort - Aggregated statistics

​
Media Module

Purpose: Centralized media upload and managementLocation: modules/media/Domain Value Objects:
  • UploadContext - Context information for uploads
  • UploadPurpose - VENUE_IMAGE, RESOURCE_IMAGE, USER_AVATAR
Use Cases:
  • UploadImageService - Upload to cloud storage (Cloudinary)
  • DeleteImageService - Remove from cloud storage
  • Image validation and optimization
Key Features:
  • Cloudinary integration for CDN delivery
  • Image transformation and optimization
  • Purpose-based upload policies
  • Public ID management for deletion
Dependencies:
  • cloudinary-http5 library

​
Admin Module

Purpose: Administrative operations and dashboard statisticsLocation: modules/admin/Use Cases:
  • GetAdminStatsService - Dashboard metrics
  • Admin actions for venue/resource approval
  • User management operations
Key Features:
  • Platform-wide statistics aggregation
  • Cross-module administrative operations
  • Approval workflows for content moderation
Output Ports:
  • AdminStatsPort - Aggregate statistics from all modules

​
Security Module

Purpose: Authentication and authorization configurationLocation: modules/security/Key Components:
  • JWT token validation (Auth0 integration)
  • Spring Security configuration
  • Role-based access control (PLAYER, OWNER, ADMIN)
  • Method-level security annotations
Authentication Flow:
  1. Frontend obtains JWT from Auth0
  2. Backend validates JWT signature and claims
  3. User profile loaded/created on first access
  4. Security context populated with user details
Authorization:
  • @PreAuthorize annotations on endpoints
  • Role hierarchy: ADMIN > OWNER > PLAYER
  • Resource ownership checks in services

​
Cross-Cutting Concerns

​
Shared Domain

Location: shared/domain/
Common value objects and utilities used across modules:
  • UserId - User identifier (UUID)
  • ImageUrl - Image URL with public ID
  • CountryCode - ISO country codes
  • UserRole - PLAYER, OWNER, ADMIN
  • MoneyUtils - Currency and decimal handling

​
Event-Driven Communication

Modules communicate via:
  • Domain Events - Published after successful transactions
  • Application Events - Spring’s event publishing mechanism
  • Ports - Cross-module dependencies via interfaces

​
Data Consistency

Strategies used:
  • Database constraints (foreign keys, exclusion constraints)
  • Domain-level validation in aggregates
  • Optimistic locking for concurrent updates
  • Transactional boundaries at use case level

​
Ports and Adapters

The hexagonal architecture uses ports and adapters to maintain separation: 
package com.ccasro.hub.modules.booking.domain.ports.out;

public interface BookingRepositoryPort {
    Booking save(Booking booking);
    Optional<Booking> findById(BookingId id);
    List<Booking> findByPlayerIdAndDateRange(UserId playerId, LocalDate from, LocalDate to);
}

Domain Model

Deep dive into domain entities and value objects

Database Schema

Complete database structure and migrations

Build docs developers (and LLMs) love

Get started for freeTalk to us