An open enterprise frontend ecosystem engineered for luxury cruise fleets.
Unifying real-time fleet command telemetry, interactive 3D vessel digital twin, voyage global lifecycle orchestration, and a standalone mobile-first guest experience portal.
Cruise-web provides a unified single-page architecture with two strictly decoupled operational domains:
| π’ Fleet Operations Command Deck | β¨ Luxury Guest Experience Portal |
|---|---|
Target: Captain, Chief Purser, Tour Guides & Port Coordinators.
|
Target: Passengers, Families, VIP Guests (Mobile-First / Tablet).
|
graph TD
classDef client fill:#0B1F33,stroke:#C5A572,stroke-width:1.5px,color:#fff;
classDef layout fill:#102A43,stroke:#397C80,stroke-width:2px,color:#fff;
classDef module fill:#071727,stroke:#64B5F6,stroke-width:1.5px,color:#fff;
classDef gateway fill:#1E293B,stroke:#F59E0B,stroke-width:2px,color:#fff;
USER["π¨ββοΈ Crew & Fleet Operators"]:::client
GUEST["π± Luxury Cruise Passengers"]:::client
subgraph Presentation ["Presentation Layer (React 19 + Vite)"]
USER -->|Authenticated Route| MAIN_LAYOUT["π’ MainLayout<br/>(Command Sidebar & Navigation)"]:::layout
GUEST -->|Guest Session Route| GUEST_LAYOUT["β¨ PassengerLayout<br/>(Luxury Mobile Stateroom Dock)"]:::layout
MAIN_LAYOUT --> GLOBE["π 3D Maritime Globe (Three.js)"]:::module
MAIN_LAYOUT --> VOYAGE["β±οΈ Voyage Phase Control Center"]:::module
MAIN_LAYOUT --> EXCURSION["π Excursion & Attendance Dispatcher"]:::module
MAIN_LAYOUT --> FLEET["β Fleet & Deck Zone Management"]:::module
GUEST_LAYOUT --> BOARDING["π« QR Boarding Pass & Muster"]:::module
GUEST_LAYOUT --> FOLIO["π³ Real-Time Folio & Dispute Engine"]:::module
GUEST_LAYOUT --> SCHEDULE["π
Personal Daily Schedule"]:::module
end
subgraph Integration ["Transport & State Gateway"]
GLOBE & VOYAGE & EXCURSION & FLEET & BOARDING & FOLIO & SCHEDULE --> AXIOS["β‘ Axios HTTP Client + SSE Stream Handler"]:::gateway
end
subgraph Backend ["Enterprise Microservices Ecosystem"]
AXIOS -->|REST API :8080| API["π’ Cruise-api (Gateway & Services)"]:::gateway
API <-->|Offline Delta Sync| POS["π± Cruise-pos (Android Edge Terminals)"]:::client
end
| Route | Viewport / Persona | Module & Core Features | State & Persistence |
|---|---|---|---|
/ |
Crew / Desktop | Fleet Operations Dashboard: Live maritime radar, 3D interactive vessel globe, fleet occupancy KPI, and port weather. | TanStack Query + SSE |
/voyage |
Crew / Desktop |
Voyage Lifecycle Control Center: Global state machine stepper (EMBARKATION AT_SEA PORT_VISIT DEBARKING), port timezone coordinator. |
REST API + State Machine |
/ships |
Crew / Desktop | Fleet Specification Management: Hull dimensions, beam, draft, passenger/crew ratios, and deck cabin inventories. | Modal Form + Validation |
/admin/cruise-area-policies |
Crew / Desktop | Maritime Area & Cancellation Policies: Regional cruise zones, dynamic cancellation penalties, and weather advisories. | REST API + Policy Engine |
/itinerary |
Crew / Desktop | Voyage Itinerary & Timeline: Chronological ports of call, docking/undocking timetables, and audit history comparison. | Timeline Drag & Audit Log |
/excursions |
Crew / Desktop | Shore Excursion Catalog & Dispatch: Partner tour directory, bus allocation, pricing, and all-aboard deadlines. | Filtered Roster + Quotas |
/excursion-attendance |
Crew / Tablet | Excursion Roster Check-in: Real-time QR scanner and RFID tap attendance verification for departing buses. | Camera Viewfinder + Sync |
/passengers |
Crew / Desktop | Passenger Identity & Card Pool: Cabin assignments, blank RFID card batch ingestion, and lost-badge blacklisting. | Search & Batch Actions |
/pos |
Crew / Tablet | Web Cashless POS & Folio Tender: Stateroom checkout, digital e-signature pad with gesture lock, and receipt printing. | Touch-Safe Canvas Pad |
/passenger-home |
Guest / Mobile | Luxury Guest Hub: Personalized cabin welcome, onboard credit (OBC) balance pill, and vessel weather widget. | Standalone Luxury Theme |
/boarding-pass |
Guest / Mobile | Digital Boarding Pass: High-contrast offline QR pass with muster station designation and boarding group badge. | SVG Barcode Renderer |
/my-schedule |
Guest / Mobile | Personal Itinerary: Booked excursions, spa appointments, and theater reservations with countdown alerts. | Reactive Schedule Grid |
/passenger/folio |
Guest / Mobile | Real-Time Stateroom Folio: Itemized transaction ledger, instant dispute filing, and split-cabin preview. | Folio Stream + E-Receipts |
The visual identity is custom-crafted to reflect the prestige of international superyachts and luxury ocean liners:
- Node.js: v22.x or later
- npm: v10.x or later
# 1. Clone repository and navigate to directory
git clone https://github.com/Cruise-JavaCLass/Cruise-web.git
cd Cruise-web
# 2. Install dependencies cleanly
npm install
# 3. Start local development server with Hot Module Replacement
npm run devThe application will initialize at
http://localhost:3000with immediate proxying to Backend Gateway athttp://localhost:8080.
# Typecheck and compile optimized production bundle into /dist
npm run build
# Preview production build locally
npm run previewThe codebase enforces strict unit, integration, and component testing via Vitest and React Testing Library:
| Command | Target | Description |
|---|---|---|
npm test |
All Suites | Headless single-pass test execution with standard exit codes. |
npm run test:watch |
Interactive | Hot-reloading test runner for ongoing feature development. |
npm run test:coverage |
V8 Coverage | Generates statement, branch, and function coverage reports at ./coverage. |
npm run test:ui |
Browser UI | Launches interactive visual test explorer in browser. |
npm run test:ci |
CI Pipeline | High-verbosity reporting with strict failure thresholds for GitHub Actions. |
# Run targeted tests for a specific operational module
npx vitest run src/components/voyage/VoyageLifecycle.test.tsx
npx vitest run src/pages/PassengersPage.test.tsxDevelopment strictly adheres to GitHub Flow and Conventional Commits:
- Feature Branches:
feature/<JIRA-KEY>-<short-description> - Bugfix Branches:
bugfix/<JIRA-KEY>-<short-description> - Commit Specification:
[<JIRA-KEY>] <type>(<scope>): <imperative summary> - Continuous Integration: Every PR automatically triggers GitHub Actions running:
Oxlintstatic AST analysis & syntax validation.TypeScriptstrict compiler verification (tsc --noEmit).Vitestunit and integration test suite with coverage thresholds.Viteproduction bundle build verification.
Cruise Hospitality Technology β’ Engineered for Luxury Maritime Operations
Cruise Management System Β© 2026. Distributed under the MIT License.