An open-standard, distributed backend ecosystem engineered for luxury cruise fleet operations.
Orchestrating mission-critical nautical compliance, SOLAS Chapter III real-time muster telemetry, distributed multi-schema PostgreSQL persistence, dynamic cryptographic QR access control, and offline-tolerant POS retail accounting.
📑 Table of Contents (Click to explore)
- 1. Executive Architectural Overview
- 2. Microservices Topology & Bounded Contexts
- 3. System Architecture & Topology Diagram
- 4. Mission-Critical Maritime Specifications
- 5. One-Click Developer Orchestration
- 6. Automated Postman Enterprise Test Suite
- 7. Complete REST API Matrix (38 Endpoints)
- 8. Quality Assurance, SonarCloud & CI/CD
- 9. Governance & License
Cruise-api serves as the centralized computational backbone for the Grand Pearl Voyager luxury cruise management fleet. Engineered with Spring Boot and Java 21, the system decouples complex maritime logistics into 5 autonomous, loosely coupled microservices bound together by standardized REST contracts and isolated database schemas.
Note
Maritime Reliability Standard: Designed to operate smoothly during deep-sea oceanic transits where satellite uplink latency varies from 20ms to high-jitter disconnected states, ensuring offline resilience and strict operational integrity.
Each bounded context maintains absolute domain autonomy, backed by its dedicated PostgreSQL database schema to enforce transactional isolation.
| Microservice | Port | Schema Isolation | Core Capabilities & Nautical Responsibilities |
|---|---|---|---|
cruise-gatewayGateway Entrypoint |
8080 |
Stateless (None) |
• Central API reverse proxy & health telemetry coordinator. • Unified sub-millisecond heartbeat probes ( /ping, /info, /health).• Cross-Origin Resource Sharing (CORS) security enforcement. |
cruise-auth-serviceIdentity & Access |
8081 |
auth_schema |
• Dual-token authentication (HMAC-SHA256 JWT Access + Rotating Refresh Token). • Role-Based Access Control (RBAC) across 8 nautical ranks. • RFC 7662 Token Introspection & instant blacklist revocation. |
cruise-itinerary-serviceFleet & Navigation |
8082 |
itinerary_schema |
• Vessel master registry (tonnage, dimensions, stateroom tiers, decks). • Global port of call catalog & docking berth coordination. • Master sailing itineraries, waypoint scheduling & maritime cabotage policies. |
cruise-activity-serviceExcursions & Safety |
8083 |
activity_schema |
• Gala dinners, Broadway theatricals & wellness scheduling. • Shore excursions (capacity locking, pricing, bus dispatching, guide rosters). • SOLAS Compliance: All-Aboard departure countdown & Muster drills. • Cryptographic dynamic QR pass generation (60s TTL). |
cruise-pos-serviceRetail, Folio & Billing |
8084 |
pos_schema |
• Onboard retail catalogs (dining, bars, spa, boutiques). • Cashier shift lifecycle, safe cash drops & mid-day X-Reports. • Passenger stateroom folio accounting, cabin charging & disputes. • Voyage State Machine: Transactional phase locking. |
cruise-commonShared Core Library |
Library | N/A |
• Universal response projections (ApiResponse<T>, pagination metadata).• Global error codes, security annotations & domain enumerations. |
graph TD
classDef client fill:#0B1F33,stroke:#C5A572,stroke-width:1.5px,color:#fff;
classDef gateway fill:#1E293B,stroke:#F59E0B,stroke-width:2px,color:#fff;
classDef service fill:#102A43,stroke:#397C80,stroke-width:2px,color:#fff;
classDef database fill:#071727,stroke:#64B5F6,stroke-width:1.5px,color:#fff;
subgraph CLIENT_TIER ["🖥️ Client Presentation Layer"]
WEB["Cruise-web (Command Deck & Guest Portal - :3000)"]:::client
POS["Cruise-pos (Point of Sale Bar & Dining Terminals)"]:::client
MOBILE["Handheld RFID Keycard & Dynamic QR Scanners"]:::client
end
subgraph GATEWAY_TIER ["🛡️ API Gateway Tier"]
GW["cruise-gateway (:8080)<br/>CORS • Telemetry • Health Probes"]:::gateway
end
subgraph SERVICES_TIER ["⚙️ Microservices Domain Tier"]
AUTH["cruise-auth-service (:8081)<br/>Dual JWT • RBAC • RFC 7662"]:::service
ITIN["cruise-itinerary-service (:8082)<br/>Fleet • Ports • Master Tours"]:::service
ACT["cruise-activity-service (:8083)<br/>Excursions • Attendance • SOLAS"]:::service
POS_SVC["cruise-pos-service (:8084)<br/>Folios • Shifts • Voyage FSM"]:::service
end
subgraph DATA_TIER ["🐬 PostgreSQL 18 Multi-Schema Persistence (:5432)"]
DB_AUTH[("auth_schema<br/>Users • Roles • Revocations")]:::database
DB_ITIN[("itinerary_schema<br/>Vessels • Berths • Waypoints")]:::database
DB_ACT[("activity_schema<br/>Bookings • Rosters • Drills")]:::database
DB_POS[("pos_schema<br/>Transactions • Shifts • Folios")]:::database
end
CLIENT_TIER --> GW
CLIENT_TIER -. Direct Microservice REST .-> SERVICES_TIER
GW --> AUTH
GW --> ITIN
GW --> ACT
GW --> POS_SVC
AUTH --> DB_AUTH
ITIN --> DB_ITIN
ACT --> DB_ACT
POS_SVC --> DB_POS
In accordance with the International Convention for the Safety of Life at Sea (SOLAS):
- Mandatory Muster Station Drills:
SolasMusterEmergencyControllerenforces compulsory digital verification of guest emergency stations before any vessel unmoors from port. - All-Aboard Watchdog:
AllAboardWatchdogControllermaintains a real-time countdown sync between shore excursion attendance rosters and ship departure schedules to eliminate abandoned passengers.
- Issued through
QrTokenServiceutilizing an HMAC-SHA256 signature with an ephemeral 60-second Time-To-Live (TTL). The signing key is supplied via theCRUISE_QR_SECRETenvironment variable (with local test fallback restricted to thedevprofile). - The 60-second TTL limits the replay window, mitigating ticket scalping and unauthorized access to VIP lounges or high-capacity tender boats.
Every voyage adheres to a strict, transactional sequence enforced across all endpoints:
stateDiagram-v2
[*] --> SCHEDULED: Voyage Planning
SCHEDULED --> EMBARKATION: Terminal Check-in Opens
EMBARKATION --> AT_SEA: All-Aboard Verified & Departed
AT_SEA --> PORT_CALL: Docked at Shore Destination
PORT_CALL --> AT_SEA: Excursions Completed & Underway
AT_SEA --> DISEMBARKING: Final Port Arrival
DISEMBARKING --> CLOSED: Folios Audited & Shifts Reconciled
CLOSED --> [*]
- JDK 21 LTS (
java -versionreturns Java 21) - Docker Desktop running (for PostgreSQL 18)
- Node.js & npm (Node.js 18+ for running Newman CLI via
npx newman) - Postman Desktop (for visual test execution)
You can launch the entire infrastructure in seconds using the idempotent root scripts:
:: 1. Package all microservices (required on clean checkout)
.\mvnw.cmd clean package -DskipTests
:: 2. Launch PostgreSQL and all 5 Microservices in dedicated, titled consoles
run-all-services.bat
:: Stop all running microservices and release ports cleanly
stop-all-services.batTip
Idempotent Automation: run-all-services.bat automatically terminates any stale processes lingering on ports 8080-8084, validates that all packaged JARs exist in target/, waits for the Docker PostgreSQL container to become healthy via docker compose up -d --wait, ensures CRUISE_QR_SECRET is set, and spins up all 5 microservices cleanly.
# 1. Start the PostgreSQL 18 container with pre-configured schemas
docker compose up -d
# 2. Build and install common DTOs and contracts
./mvnw -pl cruise-common install -DskipTests
# 3. Launch individual services as needed
./mvnw -pl cruise-gateway spring-boot:run # Port 8080
./mvnw -pl cruise-auth-service spring-boot:run # Port 8081
./mvnw -pl cruise-itinerary-service spring-boot:run # Port 8082
./mvnw -pl cruise-activity-service spring-boot:run # Port 8083
./mvnw -pl cruise-pos-service spring-boot:run # Port 8084The project includes an enterprise-grade automated Postman test suite located in docs/postman/:
- 📦 Collection:
Cruise_Management_System_v1.0.0.postman_collection.json - 🌐 Environment:
Cruise_Local.postman_environment.json
| Variable | Value | Description |
|---|---|---|
baseUrl |
http://localhost:8080/api |
Gateway Unified API Base URL |
gatewayUrl |
http://localhost:8080 |
Gateway Root Service URL |
authUrl |
http://localhost:8081 |
Authentication Microservice URL |
itineraryUrl |
http://localhost:8082 |
Itinerary & Fleet Microservice URL |
activityUrl |
http://localhost:8083 |
Activity & SOLAS Microservice URL |
posUrl |
http://localhost:8084 |
POS & Folio Microservice URL |
jwt_token |
(Dynamic) | Auto-populated by Admin Login request |
admin_username |
admin |
Default Maritime Admin identifier |
admin_password |
admin123 |
Default Maritime Admin credential |
# Run the entire 37-endpoint suite with terminal summary table
npx --yes newman run docs/postman/Cruise_Management_System_v1.0.0.postman_collection.json \
-e docs/postman/Cruise_Local.postman_environment.json \
--reporters cli00 - Gateway & System Monitoring (Port 8080)
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/ping |
Gateway high-speed heartbeat check (pong) |
GET |
/api/info |
Application specifications, runtime JVM and build version |
GET |
/api/health |
Memory allocation (used/free), uptime and status |
01 - Authentication & User Security (Port 8081)
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/auth/health |
Auth microservice readiness probe and supported roles |
POST |
/api/auth/login |
Authenticate crew member & auto-capture JWT Bearer token |
GET |
/api/auth/me |
Retrieve profile and assigned rank of authenticated user |
POST |
/api/auth/verify-token |
Token Introspection (RFC 7662) and cryptographic verification |
POST |
/api/auth/refresh |
Refresh Token rotation for continuous nautical operations |
POST |
/api/auth/verify-password |
Credential verification without token generation |
POST |
/api/auth/users |
Register new crew officer profile |
GET |
/api/auth/users/{username} |
Fetch staff details and assigned operational privileges |
POST |
/api/auth/logout |
Revoke active access token and commit to blacklist |
02 - Fleet & Itinerary Operations (Port 8082)
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/itinerary/ships |
Master fleet vessel catalog and gross tonnage specs |
GET |
/api/itinerary/ports |
International ports of call and docking berths |
GET |
/api/itinerary/tours |
Master sailing itineraries and voyage packages |
GET |
/api/itinerary/tours/{id}/daily |
Day-by-day navigation breakdown and cruising legs |
GET |
/api/itinerary/tours/{id}/stops |
Waypoint arrival/departure timeline and nautical miles |
GET |
/api/admin/cruise-area-policy |
Maritime cabotage boundaries and regional sailing restrictions |
03 - Shore Excursions & Activities (Port 8083)
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/activities/health |
Activity microservice health and SOLAS readiness |
GET |
/api/activities |
Scheduled onboard activities, deck events and gala dinners |
POST |
/api/activities |
Schedule a new event on the ship master calendar |
GET |
/api/excursions |
Port shore excursions, bus quotas and guide assignments |
GET |
/api/passenger-portal/catalog |
Guest-facing excursion catalog with pricing and duration |
GET |
/api/operations/dashboard |
Live attendance metrics, quota burn rate and roster counts |
GET |
/api/operations/all-aboard-watchdog |
SOLAS Chapter III All-Aboard departure countdown |
GET |
/api/operations/solas-muster |
Emergency lifeboat muster station drill verification |
GET |
/api/operations/rfid-cards |
Active contactless keycards and RFID wristband registry |
GET |
/api/operations/notifications |
Broadcast operational bulletins and storm track advisories |
04 - POS, Folios & Voyage Lifecycle (Port 8084)
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/pos/catalog |
Dining, bar lounge, spa and retail boutique catalog |
GET |
/api/pos/shifts |
Active cashier terminals and cashier register status |
GET |
/api/pos/shifts/current/x-report |
Mid-day sales snapshot, card totals and cash drawer balance |
GET |
/api/pos/shifts/cash-drops |
Audit trail of physical cash drops deposited to safe |
GET |
/api/pos/folios |
Passenger onboard spending accounts and credit limits |
GET |
/api/admin/pos/terminals |
Registered physical POS terminal hardware authorization |
GET |
/api/pos/cabin-billing |
Aggregated stateroom charges and cabin invoice breakdown |
GET |
/api/pos/disputes |
Transaction dispute log and chargeback handling |
GET |
/api/admin/voyage-lifecycle |
Voyage Phase Control Center (State transitions) |
The codebase is enforced with strict quality gates across GitHub Actions and SonarCloud:
-
Targeted Unit Tests: Coverage
$\ge 80%$ on business logic and state machines. - Security Scans: CodeQL analysis and CodeRabbit automated peer review on every pull request.
- SonarCloud Quality Gate: Zero blocker bugs, zero security vulnerabilities, zero code smells.
# Execute full Maven test suite
./mvnw test -q
# Execute targeted service tests
./mvnw test -pl cruise-auth-service -Dtest=AuthServiceTest -q
./mvnw test -pl cruise-activity-service -Dtest=ActivityAttendanceServiceTest -q
# Run SonarCloud scanner
./mvnw clean verify sonar:sonarDistributed under the MIT License.
Maintained with pride by the Cruise Hospitality Technology Engineering Team.
For companion frontend repositories, visit Cruise-web and Cruise-pos.