System Requirements Document

Mindanao Travel Ticketing Hub (MTTH)

Project Name: silver-website

1. Introduction

1.1 Purpose

This System Requirements Document (SRD) defines the complete functional, experiential, and technical requirements for the Mindanao Travel Ticketing Hub (MTTH) — a professional, responsive, full-stack transportation ticketing and travel discovery platform for travelers in the Philippines, with strong emphasis on Mindanao transportation, destinations, routes, affordable travel, repeat travelers, and local travel discovery.

1.2 Brand

• Product Name: Mindanao Travel Ticketing Hub (MTTH)
• Project Name: silver-website
• Brand Tagline: Your Journey Starts Here.
• Secondary Tagline: Book. Explore. Save. Travel More.

1.3 Primary Product Focus

Plane Tickets, Bus Tickets, Ferry Tickets, Digital Travel Tickets, Travel Discounts, Discount Codes, Travel Vouchers, Suki Traveler Rewards, Mindanao Destination Discovery, Travel Guides, Trip Planning, Traveler Tools, and Mobile Travel Experience.

1.4 Primary Customer Journey

SEARCH → COMPARE → SELECT → APPLY DISCOUNT → BOOK → PAY → RECEIVE DIGITAL TICKET → TRAVEL → EARN POINTS → DISCOVER ANOTHER DESTINATION

1.5 Product Vision

The platform makes transportation booking across Mindanao easier, more transparent, more convenient, and more rewarding. It is defined as a combination of a Travel Marketplace + Booking Engine + Travel Guide + Loyalty Platform + Digital Ticket Wallet + Mindanao Tourism Discovery Platform.

1.6 Problems the Platform Solves

Finding available transportation; comparing schedules; comparing prices; finding affordable routes; discovering destinations; finding transportation connections; applying discounts; using vouchers; earning loyalty points; keeping tickets in one place; managing multiple trips; planning multi-leg journeys; finding useful travel information; receiving booking notifications; managing cancellations; understanding travel requirements; and discovering local destinations.

1.7 Absolute Product Rules

1. The platform must NOT be an event ticketing marketplace.
2. Only transportation ticketing is the primary booking product: Flights + Buses + Ferries.
3. Mindanao travel discovery must be a major part of the product.
4. Suki Traveler must be a major loyalty feature.
5. Discount codes and vouchers must be functional in the application architecture.
6. The traveler must be able to see exactly how much they save.
7. The system must support digital tickets and QR validation.
8. The system must not fabricate live transportation information.
9. Demo schedules, fares, operators, promotions, and availability must be clearly identified as demo data until connected to live provider APIs.
10. The system must not claim a destination is objectively the most visited without verified current tourism data.
11. All transportation operators must be configurable.
12. All voucher rules must be configurable.
13. All Suki reward rules must be configurable.
14. All cancellation and refund rules must be configurable per operator/route.
15. The system must never expose sensitive user or payment information.
16. The platform must NOT be an event ticketing marketplace; only transportation ticketing (Flights + Buses + Ferries) is the primary booking product.

1.8 Final Experience Statement

The entire application revolves around one simple idea: TRAVEL SHOULD BE EASY. A traveler must be able to say "I want to travel from Cagayan de Oro to Camiguin" and be helped to find transportation, compare prices, choose a schedule, apply a discount, use a voucher, earn Suki points, book securely, receive a digital ticket, plan their trip, discover things to do, and travel confidently — then be inspired with "Where should I go next?"

2. System Overview

2.1 Delivery Shape

A complete, professional, responsive, full-stack transportation ticketing and travel discovery platform. It is explicitly not a simple landing page, visual mockup, static prototype, or design concept. It must be generated as a working product with frontend, backend, database, APIs, authentication, booking workflows, transportation search, checkout, payment architecture, digital tickets, QR codes, Suki Rewards, vouchers, discount codes, travel guides, Mindanao destination discovery, itinerary planning, traveler dashboard, operator dashboard, administrator dashboard, analytics, notifications, responsive mobile layouts, accessibility features, SEO, and demo data.

2.2 Core Transportation Types

• Flights: one-way, round-trip, multi-city architecture, domestic flights, airport selection, cabin selection, passenger selection, baggage information, and seat selection where supported.
• Bus: city-to-city and province-to-province routes, terminal selection, bus operator, bus type, seat selection, departure time, arrival time, travel duration, and baggage rules.
• Ferry: port-to-port routes, passenger categories, accommodation class, cabin selection, seat/berth selection where applicable, vehicle transport architecture, boarding requirements, and port fees.

2.3 Major Product Pillars

Transportation booking and search; digital ticket wallet with QR validation; Suki Traveler Rewards loyalty program; vouchers, promo codes, and flash sales; Explore Mindanao destination discovery; travel guides; travel planner and itinerary builder; traveler tools (profile, favorites, price alerts, rebooking); operator dashboards; and administrator control center.

2.4 Architecture Principle

Build using clean architecture. Do not put everything in one file or create a single massive component. Separate UI, business logic, API, database, authentication, payments, booking, loyalty, content, and analytics.

2.5 Quality Standard

The completed platform must look like something that could realistically become a commercial Philippine travel startup. It must NOT look like a generic school project, basic CRUD app, Bootstrap template, static mockup, generic AI website, or simple landing page. It must look like a real transportation booking platform + travel discovery ecosystem.

3. Functional Requirements

3.1 Homepage & Header

• FR-001: As a traveler, I want an exceptionally polished homepage that immediately answers what the website does, where I can travel, whether I can book a bus/ferry/flight, whether I can save money, what destinations I can discover, and why I should trust the platform.
• FR-002: As a desktop traveler, I want a sticky responsive header containing the MTTH logo, Home, Flights, Buses, Ferries, Destinations, Deals, Travel Guide, Suki Rewards, Search, Notifications, My Trips, Sign In, and Book Now.
• FR-003: As a mobile traveler, I want a mobile header containing the logo, search icon, notification icon, and menu icon.
• FR-004: As a mobile traveler, I want a menu containing Home, Flights, Buses, Ferries, Destinations, Deals, Suki Rewards, Travel Guide, My Trips, Profile, and Help.
• FR-005: As a traveler, I want a hero section with the headline "Your Journey Starts Here.", the subheading "Book flights, ferries, and buses across Mindanao and discover affordable ways to explore the Philippines.", a primary CTA "Search Trips", and a secondary CTA "Explore Mindanao".
• FR-006: As a traveler, I want the hero to use premium travel photography featuring oceans, islands, mountains, highways, bus terminals, ferry ports, airports, travelers, and sunrise/sunset scenes.
• FR-007: As a traveler, I want a final homepage structure consisting of: Sticky Header, Hero, Booking Search, Quick Transportation Tabs, Travel Deals, Suki Rewards, Popular Mindanao Destinations, Popular Routes, Weekend Escapes, Travel Guides, Trip Planner, Why Choose MTTH, Verified Operators, Traveler Reviews, Newsletter, and Footer.
• FR-007a: As a traveler, I want the homepage to open with a full-bleed dark hero: a cinematic photograph of a ferry cutting through dark water at dawn, desaturated toward graphite with a champagne-gold horizon line, overlaid by a left-aligned 9-column condensed headline "YOUR JOURNEY STARTS HERE." set in Barlow Condensed 700 at clamp(40px, 7vw, 96px), uppercase, tight leading; beneath it a single line of Saira body copy at 18px in #F2F0EB at 90%; two CTAs as instrument chips — "Search Trips" in solid champagne #C9A66B with dark text and "Explore Mindanao" in a 1px outline chip; and the booking search widget floating below, overlapping the hero's bottom edge as a dark instrument panel with three tabs (Flights / Buses / Ferries), each field labeled in 12px uppercase tracked text, and a right-aligned circular gauge showing "3 modes · 47 operators · live". No centered headline, no subtext stack, no blue button, no gradient blob.

3.2 Booking Search Widget & Search Input

• FR-008: As a traveler, I want a booking search widget placed prominently below or overlapping the hero, with Flights, Buses, and Ferries tabs.
• FR-009: As a traveler, I want Flight Search fields for From, To, Trip Type, Departure, Return, Travelers, and Cabin, with a "Search Flights" CTA.
• FR-010: As a traveler, I want Bus Search fields for From, To, Departure, Passengers, Bus Type, and Seat Preference, with a "Search Buses" CTA.
• FR-011: As a traveler, I want Bus Type options of Ordinary, Aircon, Deluxe, Sleeper, and Premium.
• FR-011a: As a traveler, I want the booking search widget rendered as an instrument-panel: a dark #1A1F24 panel with a 1px inner top highlight, tabbed Flights/Buses/Ferries, each field as a labeled instrument readout with a small gauge or chevron, and a live availability dial on the right edge.
• FR-012: As a traveler, I want Ferry Search fields for From Port, To Port, Departure Date, Passengers, Passenger Type, and Accommodation, with a "Search Ferries" CTA.
• FR-013: As a traveler, I want Ferry Passenger Type options of Adult, Child, Senior Citizen, Student, and Infant.
• FR-014: As a traveler, I want Ferry Accommodation options of Economy, Tourist, Business, Cabin, and VIP, where supported.
• FR-015: As a traveler, I want search autocomplete that understands city, province, airport, port, and terminal, and provides intelligent suggestions when I type partial place names.

3.3 Search Results, Filters & Sorting

• FR-016: As a traveler, I want a highly functional results page with a route summary, date, traveler count, result count, filters, sorting, and detailed result cards.
• FR-017: As a traveler, I want filters for Price, Departure, Arrival, Operator, Travel Duration, Vehicle Type, Seat Type, Baggage, Refundable, Available Seats, Discount Available, and Suki Eligible.
• FR-018: As a traveler, I want sorting options for Recommended, Cheapest, Fastest, Earliest, Latest, Best Rated, and Best Value.
• FR-019: As a traveler, I want each result card to show operator logo, verified badge, departure, arrival, duration, stops, vehicle type, seat availability, baggage, price, discount, and a CTA.
• FR-020: As a traveler, I want a price breakdown showing Base Fare, Terminal Fee, Service Fee, Taxes, Discount, Voucher, Suki Discount, and Final Total.
• FR-020a: As a traveler, I want the price breakdown rendered as a ruled instrument row: Base Fare, Terminal Fee, Service Fee, Taxes, Discount, Voucher, Suki Discount, and Final Total as aligned label/value rows with hairline dividers and the Final Total in champagne at 2x size — a receipt that looks like a cockpit readout.
• FR-021: As a traveler, I want to compare up to three travel options by price, duration, departure, type, and baggage.

3.4 Booking Details & Passenger Information

• FR-022: As a traveler, after selecting transportation, I want to see journey, origin, destination, date, time, operator, vehicle, seat, and passenger count.
• FR-023: As a traveler, I want to provide full name, date of birth, gender, mobile number, email, and government ID details only where required, and never be asked for unnecessary sensitive information.
• FR-024: As a logged-in traveler, I want to save frequent passengers securely.
• FR-025: As a traveler, for supported operators, I want an interactive seat map showing available, selected, occupied, reserved, and premium seats.
• FR-025a: As a traveler, I want the seat map to use precise rectangular cells with a 2px selected stroke, consistent with the instrument geometry of the interface.
• FR-026: As a traveler, I want baggage information displaying included baggage, hand carry, and additional baggage, with policies configurable per operator and route.

3.5 Checkout, Discounts & Payment

• FR-027: As a traveler, I want a four-step checkout flow: Traveler, Review, Payment, and Confirmation.
• FR-028: As a traveler, I want a visible promo-code field with an Apply action and a clear savings display.
• FR-029: As a traveler, I want a voucher wallet allowing me to select eligible vouchers from my account.
• FR-030: As an eligible traveler, I want to see my Suki tier and discount.
• FR-031: As a traveler, I want a payment architecture supporting GCash, Maya, credit card, debit card, online banking, and payment gateway abstraction, without claiming real processing unless connected to a real provider, and including a demo payment mode.
• FR-032: As a traveler, I want a booking confirmation showing booking number, transportation type, operator, route, date, time, passenger, seat, total paid, discount, voucher, and Suki points earned.
• FR-033: As a traveler, on the booking confirmation I want View Ticket, Download Ticket, and Add to Trip actions.

3.6 Digital Ticket & QR Code

• FR-034: As a traveler, I want a professional digital boarding pass for bus, ferry, and flight tickets showing passenger, origin, destination, date, departure, arrival, seat, terminal/gate where applicable, booking number, and QR code.
• FR-035: As a traveler, I want the QR code to use a secure ticket identifier rather than raw personal information.
• FR-036: As a system, I must perform server-side validation that verifies ticket existence, ownership, validity, cancellation status, and check-in status.
• FR-036a: As a system, I must provide a QR / ticket validation service that issues secure ticket identifiers and performs server-side validation.
• FR-037: As a mobile traveler, I want a digital ticket mobile experience with a large QR code, important information above the fold, and a Show Ticket CTA.

3.7 My Trips & Trip Timeline

• FR-038: As a traveler, I want a My Trips page at route /my-trips with Upcoming, Completed, and Cancelled tabs.
• FR-039: As a traveler, I want each trip to show route, date, time, operator, ticket status, and a View Ticket action.
• FR-040: As a traveler, I want a trip timeline of Booking Confirmed → Payment Completed → Ticket Issued → Travel Reminder → Boarding → Completed.
• FR-041: As a traveler, I want travel reminders 7 days before, 24 hours before, and 3 hours before departure, plus post-trip feedback requests.
• FR-042: As a traveler, I want verified travel alerts displaying schedule changes, terminal changes, port changes, weather alerts, delays, cancellations, and boarding reminders, with real alerts only shown when connected to verified sources.

3.8 Cancellation & Refunds

• FR-043: As a traveler, I want a cancellation flow showing policy, refund eligibility, refund amount, fees, and final refund.
• FR-044: As a traveler, I want a refund lifecycle of Requested → Under Review → Approved → Processing → Completed, or Rejected.

3.9 Suki Traveler Rewards

• FR-045: As a traveler, I want the Suki core message "The more you travel, the more you save."
• FR-046: As a traveler, I want Suki points earned from completed bookings, eligible routes, promotions, referrals, reviews, birthday bonuses, first booking, and seasonal campaigns.
• FR-047: As a traveler, I do not want points awarded for cancelled or fraudulent transactions.
• FR-048: As a traveler, I want Suki tiers of STARTER (0–999 points), PLUS (1,000–2,999 points), GOLD (3,000–5,999 points), and VIP (6,000+ points), with all thresholds and benefits configurable.
• FR-048a: As a traveler, I want the Suki Rewards homepage section to open with a hairline rule and a small uppercase section code "03 / SUKI REWARDS" in champagne gold at 13px tracked +0.12em.
• FR-049: As a traveler, I want a Suki dashboard displaying tier, points, progress to next tier, available vouchers, completed trips, rewards, and earning opportunities.
• FR-050: As a traveler, I want a point history showing date, activity, points earned or redeemed, and balance.

3.10 Vouchers, Promo Codes & Flash Sales

• FR-051: As a traveler, I want a voucher center with fixed and percentage travel vouchers, including minimum booking requirements, expiration, usage limits, eligible transport, route, destination, and Suki requirements.
• FR-052: As a traveler, I want promo codes supporting percentage discounts, fixed discounts, route-specific discounts, operator-specific discounts, destination discounts, transport-type discounts, minimum-spend discounts, first-booking discounts, and Suki-only promotions.
• FR-053: As a traveler, I want demo promo codes including WELCOME10, MINDANAO200, SUKIGOLD, WEEKEND150, FLYMINDA, FERRYFUN, and BUSBUDDY, clearly marked as demo promotions.
• FR-054: As a traveler, I want flash sales with time-limited promotional cards showing original price, discounted price, discount percentage, countdown, and a Book Deal CTA, with demo prices clearly identified as examples.

3.11 Explore Mindanao — Destination Discovery

• FR-055: As a traveler, I want a major "Explore Mindanao" feature with supporting text "Discover beaches, mountains, waterfalls, islands, food, culture, and unforgettable adventures across Mindanao."
• FR-056: As a traveler, I want each destination to contain name, slug, province, region, hero image, short description, long description, attractions, best time to visit, recommended duration, budget estimate, transportation options, nearby airports, nearby ports, nearby terminals, travel tips, activities, travel guides, and related destinations.
• FR-057: As a traveler, I want a Camiguin destination page titled "Island Born of Fire" including White Island, Mantigue Island, Sunken Cemetery, Katibawasan Falls, Tuasan Falls, hot springs, local food, transportation, itineraries, and ticket links.
• FR-058: As a traveler, I want a Cagayan de Oro destination page ("City of Golden Friendship") including whitewater rafting, food, shopping, adventure, nearby destinations, Camiguin gateway, Bukidnon gateway, and Iligan connections.
• FR-059: As a traveler, I want a Bukidnon destination page ("Highlands, Adventure & Nature") including mountain scenery, pine forests, farms, adventure parks, cultural experiences, road trips, and cool-weather destinations.
• FR-060: As a traveler, I want a Davao City destination page ("Urban Energy Meets Nature") including Mount Apo, Philippine Eagle Center, food, culture, Samal access, city attractions, and nearby destinations.
• FR-061: As a traveler, I want a Siargao destination page ("Island Adventures & Surf Culture") including Cloud 9, island hopping, Sugba Lagoon, Magpupungko, mangroves, surfing, cafes, and local culture.
• FR-062: As a traveler, I want a Zamboanga City destination page ("Culture, Coastlines & Heritage") including Great Santa Cruz Island, Fort Pilar, beaches, food, and cultural attractions.
• FR-063: As a traveler, I want a Lake Sebu destination page ("Culture & Highland Nature") including lakes, Seven Falls, T'boli culture, nature, local crafts, and adventure.
• FR-064: As a traveler, I want an Iligan City destination page ("City of Majestic Waterfalls") including Tinago Falls, Maria Cristina Falls, nature, adventure, and local food.
• FR-065: As a traveler, I want a Surigao destination page ("Gateway to Island Adventures") including Siargao connection, Bucas Grande, Sohoton, island travel, and coastal adventures.
• FR-066: As a traveler, I want a Dinagat Islands destination page including beaches, rock formations, island hopping, coastal communities, and nature.
• FR-067: As a traveler, I want a Mati destination page including Dahican Beach, surfing, nature, coastal scenery, and local food.
• FR-068: As a traveler, I want a General Santos destination page ("Tuna Capital & Southern Gateway") including food, tuna industry, shopping, nearby destinations, and cultural attractions.
• FR-069: As a traveler, I want a Butuan destination page ("History & CARAGA Gateway") including heritage, museums, river culture, nature, and regional transportation connections.
• FR-070: As a traveler, I want a Tinuy-an Falls attraction page with waterfall, nature, photography, adventure, and local community content.
• FR-071: As a traveler, I want an Enchanted River page covering clear water, nature, adventure, local culture, where to stay, how to get there, and nearby attractions.
• FR-072: As a traveler, I want an interactive Mindanao destination map with markers for destinations, airports, ports, bus terminals, and attractions, with filters for beaches, mountains, waterfalls, cities, islands, cultural sites, airports, and ports.
• FR-072a: As a traveler, I want the Destinations and Popular Routes sections to render Mindanao as a thin gold topographic contour map on dark, with destination nodes as small instrument pins that expand into a route card on hover/focus.
• FR-073: As a traveler, I want a Route Explorer titled "Where Can You Go From Here?" showing transportation options from a selected city.
• FR-074: As a traveler, I want dynamic destination rankings such as Most Booked This Month, Most Searched This Month, Most Favorited, Trending Destinations, and Traveler Favorites, rather than permanently claiming any destination is objectively the most visited.

3.12 Travel Guide & Article System

• FR-075: As a traveler, I want a Travel Guide at route /travel-guide with categories: Beginner Guides, Budget Travel, Family Travel, Backpacking, Island Travel, Food Travel, Adventure, Transportation Tips, Airport Guides, Ferry Guides, and Bus Guides.
• FR-076: As a traveler, I want a travel article template with title, hero image, author, date, reading time, introduction, main content, travel tips, estimated budget, how to get there, things to do, transportation, related destinations, FAQ, and a Find Tickets CTA.
• FR-077: As a traveler, I want sample articles including "How to Travel from Cagayan de Oro to Camiguin", "Complete Siargao Travel Guide", "Budget Travel Guide to Bukidnon", "First-Time Ferry Traveler Guide", "How to Prepare for a Long Bus Ride", "First-Time Domestic Flight Guide", "Weekend Escape to Camiguin", "Mindanao Backpacking Route", "Best Island Destinations in Mindanao", and "Family-Friendly Mindanao Trips".

3.13 Travel Planner & Itinerary Tools

• FR-078: As a traveler, I want a Travel Planner at route /travel-planner with a wizard asking destination, dates, number of travelers, budget, and travel style.
• FR-079: As a traveler, I want an itinerary builder allowing me to create multi-day itineraries and attach tickets, destinations, activities, notes, and budget.
• FR-080: As a traveler, I want multi-transport journey support for Bus + Ferry and Bus + Ferry + Flight journeys, and the ability to organize multiple bookings.
• FR-081: As a traveler, I want a trip budget with inputs for transportation, accommodation, food, activities, shopping, emergency, and other costs, displaying an estimated total, without implying the estimate guarantees a complete trip.
• FR-082: As a traveler, I want flight, ferry, and bus travel checklists.

3.14 Traveler Profile, Favorites & Tools

• FR-083: As a traveler, I want a traveler profile with name, profile photo, email, mobile, birthday, preferred destinations, favorite transportation, Suki tier, points, vouchers, saved travelers, saved routes, and favorite destinations.
• FR-084: As a traveler, I want to save destinations, routes, operators, travel guides, and trips.
• FR-085: As a traveler, I want price alerts such as "Notify me when CDO → Manila is below\x20\xe2\x82\xb12,000," implemented as future-ready architecture for real-time fare APIs.
• FR-086: As a traveler, I want recent searches saved with a Search Again action.
• FR-087: As a traveler, I want to save frequent routes and rebook them.
• FR-088: As a traveler, I want one-tap rebooking that restores route, preferred transport, and passenger profiles while requiring confirmation of date, availability, price, and passenger details.

3.15 Loyalty Engagement & Community

• FR-089: As a traveler, I want an Invite Your Travel Buddy referral program with configurable rewards, and no rewards for fraudulent or self-referrals.
• FR-090: As a traveler, I want an optional configurable birthday reward.
• FR-091: As a traveler, I want optional travel streak badges for 3, 5, 10, and 25 completed trips.
• FR-092: As a traveler, I want a digital passport where I collect destination badges and track destinations visited.
• FR-093: As a traveler, I want achievements including First Trip, Island Hopper, Weekend Traveler, Mindanao Explorer, Suki Traveler, Frequent Flyer, Road Tripper, and Ferry Explorer.
• FR-094: As a traveler, I want an optional traveler community with traveler stories, tips, reviews, destination photos, and recommendations, with moderation.
• FR-095: As an administrator, I can approve, reject, hide, flag, or remove user-generated content.
• FR-096: As a traveler, I want traveler reviews only from verified travelers on completed bookings, covering overall, comfort, punctuality, staff, cleanliness, value, and comments.
• FR-097: As a traveler, I want trust badges of Verified Operator, Secure Booking, Verified Ticket, and Verified Traveler Review, with no fake certifications.

3.16 Operator Features

• FR-098: As a traveler, I want operator profiles displaying logo, name, verification, description, routes, ratings, reviews, policies, and contact information.
• FR-099: As an operator, I want an operator dashboard with metrics for total bookings, passengers, revenue, occupancy, cancellations, and popular routes.
• FR-100: As an operator, I want operator dashboard navigation of Dashboard, Schedules, Routes, Bookings, Passengers, Vehicles, Promotions, Reports, Reviews, and Settings.
• FR-101: As an operator, I want schedule management for route, departure, arrival, vehicle, capacity, fare, seat layout, sales start, sales end, and status.
• FR-102: As an operator, I want vehicle management for buses (vehicle number, type, capacity, seat layout, amenities).
• FR-103: As an operator, I want vehicle management for ferries (vessel, capacity, accommodation, decks).
• FR-104: As an operator, I want vehicle management for flights (airline, aircraft, cabin, seat configuration).

3.17 Administrator Features

• FR-105: As an administrator, I want an admin dashboard with metrics for Travelers, Bookings, Revenue, Flights, Buses, Ferries, Operators, Destinations, Vouchers, and Suki Members.
• FR-106: As an administrator, I want an admin sidebar containing Dashboard, Travelers, Operators, Routes, Schedules, Bookings, Payments, Refunds, Vouchers, Promo Codes, Suki Rewards, Destinations, Travel Guides, Travel Alerts, Reviews, Reports, Audit Logs, and Settings.
• FR-107: As an administrator, I want user management showing name, email, role, status, registration, last login, bookings, Suki tier, and actions.
• FR-108: As an administrator, I want operator verification as a workflow: Application → Documents → Review → Approved → Verified → Active, or Rejected/Suspended.
• FR-109: As an administrator, I want destination management to create and edit destination, description, hero image, region, province, attractions, transportation, travel guides, SEO information, and related destinations.
• FR-110: As an administrator, I want a travel guide CMS to create, edit, publish, unpublish, schedule, delete, and feature articles.
• FR-111: As an administrator, I want voucher admin to control voucher code, type, discount, minimum spend, maximum discount, dates, usage limits, eligible transport, route, destination, and Suki requirements.
• FR-112: As an administrator, I want Suki admin to control tier thresholds, point earning rules, point multipliers, rewards, expiration, promotions, and referral bonuses.
• FR-113: As an administrator, I want analytics for booking analytics, transportation analytics, destination analytics, loyalty analytics, voucher usage, and repeat travelers.

3.18 Notifications, Email & Policies

• FR-114: As a traveler, I want a notification center with booking, payment, travel reminder, voucher, Suki, promotion, operator update, and travel alert notifications.
• FR-115: As a traveler, I want email architecture supporting Welcome, booking confirmation, payment receipt, digital ticket, travel reminder, schedule change, cancellation, refund, voucher, Suki reward, and password reset.
• FR-116: As a traveler, I want every booking to show cancellation, refund, baggage, boarding, passenger requirements, and operator rules.

3.19 Traveler Support

• FR-117: As a traveler, I want a travel FAQ covering Flights, Buses, Ferries, Bookings, Payments, Vouchers, Suki, Refunds, Digital Tickets, and Travel Planning.
• FR-118: As a traveler, I want a /help page with search help, FAQ, contact support, booking assistance, refund assistance, voucher assistance, and Suki assistance.
• FR-119: As a traveler, I want a support ticket system with support request, category, booking number, message, attachments, and status, with statuses Open, In Progress, Waiting, Resolved, and Closed.
• FR-120: As a support agent, I want a contact center support dashboard with ticket ID, customer, category, priority, status, assigned agent, created, and updated.
• FR-121: As a traveler, I want a travel information disclaimer stating that schedules, fares, terminal assignments, travel restrictions, and policies are subject to change by the transportation provider or relevant authority, and that demo information must not be presented as live information.

3.20 Engagement Surfaces

• FR-122: As a traveler, I want a "Why Choose MTTH" section covering Easy Booking (search and book transportation in one place), Better Savings (vouchers, discounts, and Suki rewards), Digital Tickets (keep travel documents in one place), and Discover More (destinations and travel inspiration).
• FR-123: As a traveler, I want a trust section covering Secure Booking, Verified Operators, Transparent Pricing, Digital Tickets, and Traveler Support.
• FR-124: As a traveler, I want a newsletter section titled "Get Travel Deals in Your Inbox" so I can be the first to know about new routes, destination guides, vouchers, and travel promotions.
• FR-125: As a traveler, I want a footer with Explore (Flights, Buses, Ferries, Destinations, Deals, Travel Guide), My Travel (My Trips, Suki Rewards, Vouchers, Favorites, Travel Planner), Operators (Partner With Us, Operator Login, Operator Dashboard), Support (Help Center, Contact, Refunds, Travel Policies), and Legal (Terms, Privacy, Booking Conditions).

3.21 System & Integration Features

• FR-126: As a system, I must provide live data architecture with integration interfaces for airline APIs, bus operator APIs, ferry APIs, payment APIs, map APIs, weather APIs, and travel advisory APIs, and use clearly labeled mock services when unavailable.
• FR-127: As a system, I must provide service architecture including FlightService, BusService, FerryService, BookingService, PaymentService, VoucherService, LoyaltyService, DestinationService, TravelGuideService, NotificationService, ReviewService, and RefundService.
• FR-128: As a system, I must expose API routes: /api/auth, /api/users, /api/flights, /api/buses, /api/ferries, /api/search, /api/routes, /api/schedules, /api/bookings, /api/payments, /api/tickets, /api/vouchers, /api/promotions, /api/suki, /api/destinations, /api/guides, /api/itineraries, /api/reviews, /api/notifications, /api/operators, and /api/admin.
• FR-128a: As a system, I must provide a dedicated authentication subsystem separated from business logic, with traveler self-service enrollment and returning verification, plus role-specific returning verification for operators, administrators, and support agents.
• FR-129: As a system, I must populate demo data of at least 20 destinations, 20 routes, 15 operators, 30 schedules, 50 users, 50 bookings, 100 tickets, 20 vouchers, 10 travel guides, and 10 reviews, using realistic Philippine/Mindanao demo data clearly identified as demo data.

3.22 Personalization

• FR-130: As a traveler, I want personalized recommendations for destinations, routes, deals, vouchers, Suki offers, and recently viewed trips based on my activity and preferences.

4. User Personas

4.1 Budget Traveler

Prioritizes lowest price, discounts, vouchers, bus travel, ferry travel, affordable destinations, and weekend trips. Wants to see exactly how much they save.

4.2 Frequent Traveler

Travels regularly for work, school, family, or business. Uses Suki points, repeat booking, saved passengers, saved payment methods, favorite routes, and frequent traveler vouchers.

4.3 Student

Needs student-friendly travel, budget routes, legitimate student discounts where supported, affordable destinations, backpacking guides, and group travel.

4.4 Family Traveler

Books multiple passengers, uses child and senior passenger options, family seating, baggage information, family-friendly destinations, and itinerary management.

4.5 Business Traveler

Needs fast booking, repeat routes, saved traveler information, digital receipts, booking history, and corporate travel support architecture.

4.6 Backpacker

Focuses on cheap transportation, multi-leg trips, island destinations, bus + ferry combinations, budget itineraries, and travel guides.

4.7 OFW / Returning Filipino

Needs airport travel, domestic connections, family transportation, travel reminders, baggage information, and easy ticket access.

4.8 Transportation Operator (Partner)

Manages schedules, routes, vehicles, fares, promotions, bookings, passengers, reviews, and reports, and receives operator verification status.

4.9 Administrator

Oversees travelers, operators, routes, schedules, bookings, payments, refunds, vouchers, promo codes, Suki rewards, destinations, travel guides, travel alerts, reviews, reports, audit logs, and settings.

4.10 Support Agent

Handles support tickets and customer assistance across booking, refund, voucher, and Suki categories.

4.11 System Actors (not personas)

External airline APIs, bus operator APIs, ferry APIs, payment APIs, map APIs, weather APIs, and travel advisory APIs integrated through labeled interfaces or mock services.

4.12 External Recipients (not personas)

Newsletter subscribers receiving outbound travel deal emails.

5. Core User Flows

5.1 Booking a Trip (Primary Traveler Flow)

1. Open homepage.
2. Choose transportation (Flight, Bus, or Ferry tab).
3. Enter origin.
4. Enter destination (with autocomplete suggestions).
5. Select date.
6. Search.
7. Compare options (including up to three-option comparison).
8. Select trip.
9. Enter traveler details (or select saved passengers).
10. Apply promo code.
11. Apply voucher from voucher wallet.
12. View Suki discount.
13. Review price breakdown.
14. Pay (demo or connected provider).
15. Receive digital ticket.
16. View itinerary.
17. Receive travel reminder.
18. Travel.
19. Check in (QR validation).
20. Earn Suki points.
21. Review trip.
22. Discover next destination.
23. Book again.

5.2 Trip Planning Flow

1. Open Travel Planner /travel-planner.
2. Wizard asks destination, dates, number of travelers, budget, and travel style.
3. Build a multi-day itinerary and attach tickets, destinations, activities, notes, and budget.
4. Optionally assemble multi-transport journeys (Bus + Ferry, or Bus + Ferry + Flight).
5. Estimate trip budget across transportation, accommodation, food, activities, shopping, emergency, and other costs.
6. Use flight, ferry, or bus checklist.
7. Proceed to Find Tickets CTA to book.

5.3 Post-Trip & Loyalty Flow

1. Trip completes per trip timeline.
2. Traveler receives post-trip feedback request.
3. Traveler earns Suki points (not for cancelled or fraudulent transactions).
4. Traveler submits a verified review.
5. Suki dashboard updates tier progress; point history records the activity.
6. Traveler unlocks streak badges, achievements, and digital passport destination badges.

5.4 Operator Flow

1. Operator navigates to Operator Login / Operator Dashboard.
2. Operator completes verification (Application → Documents → Review → Approved → Verified → Active).
3. Manages schedules, routes, vehicles, promotions, and fares.
4. Monitors bookings, passengers, revenue, occupancy, cancellations, and popular routes.
5. Responds to reviews and manages settings.

5.5 Administrator Flow

1. Administrator opens Admin Dashboard.
2. Reviews metrics across Travelers, Bookings, Revenue, Flights, Buses, Ferries, Operators, Destinations, Vouchers, and Suki Members.
3. Manages users, operators, routes, schedules, bookings, payments, refunds, vouchers, promo codes, Suki rewards, destinations, and travel guides.
4. Manages travel alerts, reviews, content moderation, reports, audit logs, and settings.
5. Monitors analytics (booking, transportation, destination, loyalty, voucher usage, repeat travelers).

5.6 Support Flow

1. Traveler opens /help.
2. Uses search help, FAQ, or selects booking/refund/voucher/Suki assistance.
3. Submits a support request with category, booking number, message, and attachments.
4. Support agent tracks it in the contact center with status progressing Open → In Progress → Waiting → Resolved → Closed.

5.7 Cancellation & Refund Flow

1. Traveler opens a booking and initiates cancellation.
2. System shows cancellation policy, refund eligibility, refund amount, fees, and final refund.
3. Refund lifecycle progresses: Requested → Under Review → Approved → Processing → Completed, or Rejected.
4. Traveler notified via notification center and email.

6. Visuals, Colors, and Theme

6.1 Design Style

The website must feel premium, modern, trustworthy, and travel-focused. It must not look like a generic Bootstrap template, must not overuse gradients, and must not overcrowd pages. The interface must remain elegant and easy to understand.

6.2 Color Theme

The project uses a dark-mode precision-instrument palette (dark titanium wayfinding system). The generic indigo/blue-on-white SaaS template is forbidden for this project.

• Deep navy/blue as the primary technology color.
• Teal/green for travel and nature accents.
• Warm orange for CTAs and promotions.
• White and soft neutral surfaces.
• Additional semantic application: success color for confirmations, warning for alerts, and error for validation and failure states (per design tokens).

6.3 Imagery & Layout

Imagery is macro and cinematic Mindanao travel photography: ferry wake cut through turquoise water, bus on a coastal mountain road at dawn, aircraft wing over island silhouettes, port cranes, terminal signage, and topographic lines of Mindanao rendered as a thin gold overlay on dark. Operator logos are shown as monochrome marks on dark chips. No stock smiling people, no clip art, no gradient blobs.

• Large high-quality destination imagery (oceans, islands, mountains, highways, bus terminals, ferry ports, airports, travelers, sunrise/sunset scenes).
• Rounded cards.
• Clean typography.
• Strong spacing.
• Subtle shadows.
• Professional line icons.
• Responsive layouts.
• Modern dashboards.

6.4 Design Tokens

Reusable tokens for primary, secondary, accent, success, warning, error, background, surface, text, muted, and border. Include a consistent spacing system, border radius system, and subtle shadows.

7. Signature Design Concept

The signature concept is a premium travel-technology ecosystem: a booking marketplace fused with a destination discovery magazine and a loyalty wallet. Large destination photography anchors discovery; the deep navy → teal → warm orange palette visually separates booking mechanics (navy), travel/nature discovery (teal), and savings/CTA moments (orange). Transparent pricing is treated as a first-class visual element — every price surface reveals savings (discount, voucher, Suki) so the traveler always sees exactly how much they save. Digital tickets are presented as premium boarding passes with a prominent QR block. Dashboards for operators and administrators adopt the same clean, modern visual language rather than a utilitarian admin look.

8. Interaction Model & Motion Direction

• Mobile-first interaction: bottom navigation (Home, Search, Trips, Suki, Profile) with large touch targets, sticky CTAs, mobile filter drawers, bottom-sheet seat selection, and a sticky checkout summary.
• Search interaction: debounced autocomplete for city, province, airport, port, and terminal; server-side filtering; pagination; caching; optimized queries.
• Micro-interactions: smooth micro-interactions and subtle shadows, applied with restraint (no overuse of gradients, no overcrowding).
• Feedback states:
  • Loading: skeletons for search, destinations, trips, deals, dashboard, ticket, and travel guide content.
  • Empty: e.g., "No Trips Yet — Your next adventure is waiting." with a CTA to Explore Destinations.
  • Error: e.g., "We couldn't find available trips. Suggest another date, nearby terminal, or different destination."
  • Network failure: "Connection interrupted. Please check your internet connection and try again."
• Accessibility motion: respect reduced motion preferences.
• Component library: Button, Input, Select, DatePicker, PassengerSelector, SearchBox, BookingTabs, TransportCard, DestinationCard, DealCard, VoucherCard, TicketCard, TripCard, SukiCard, ReviewCard, NotificationItem, Modal, Drawer, Toast, Table, Chart, Badge, StatusBadge, Timeline, and Stepper.

9. Non-Functional Requirements

9.1 Accessibility

Implement WCAG 2.2 AA: keyboard navigation, focus indicators, labels, semantic HTML, ARIA, screen-reader support, color contrast, reduced motion, and accessible validation.

9.2 Mobile Experience

Mobile is a priority. Bottom navigation (Home, Search, Trips, Suki, Profile), large touch targets, sticky CTAs, mobile filter drawers, bottom-sheet seat selection, and sticky checkout summary. Digital ticket mobile experience requires a large QR code, important information above the fold, and a Show Ticket CTA.

9.3 Performance

Target fast first load, responsive interactions, optimized images, lazy loading, efficient API requests, and strong Lighthouse scores. Search performance requires debouncing, caching, pagination, server-side filtering, and optimized queries.

9.4 SEO

Every destination and travel guide page must have a title, meta description, Open Graph image, canonical URL, structured data, breadcrumbs, and FAQ schema where applicable.

9.5 Security & Privacy

• QR codes must use a secure ticket identifier rather than raw personal information.
• Server-side ticket validation must verify existence, ownership, validity, cancellation status, and check-in status.
• The system must never expose sensitive user or payment information.
• Government ID details are collected only where required; unnecessary sensitive information must not be requested.
• Payment architecture must not claim real processing unless connected to a real provider.

9.6 Data Integrity & Honesty

• Demo schedules, fares, operators, promotions, and availability must be clearly identified as demo data until connected to live provider APIs.
• Real alerts must only be shown when connected to verified sources.
• No destination may be claimed as objectively the most visited without verified current tourism data.
• No fabrication of live transportation information.

9.7 Configurability

All transportation operators, voucher rules, Suki reward rules, and cancellation/refund rules (per operator/route) must be configurable.

9.8 Architecture Quality

Clean architecture required — no monolithic single file or single massive component; UI, business logic, API, database, authentication, payments, booking, loyalty, content, and analytics must be separated.

10. Tech Stack

The platform is generated as a full-stack application via Google AI Studio, built using clean architecture with separated concerns.

10.1 Application Layers

• Responsive Web Frontend: responsive layouts, mobile-first UI, reusable component library, design tokens, loading/empty/error/network-failure states, SEO-ready destination and travel guide pages, and modern dashboards. (Must not be a generic Bootstrap template.)
• Backend Service Layer: discrete services — FlightService, BusService, FerryService, BookingService, PaymentService, VoucherService, LoyaltyService, DestinationService, TravelGuideService, NotificationService, ReviewService, and RefundService.
• API Layer: /api/auth, /api/users, /api/flights, /api/buses, /api/ferries, /api/search, /api/routes, /api/schedules, /api/bookings, /api/payments, /api/tickets, /api/vouchers, /api/promotions, /api/suki, /api/destinations, /api/guides, /api/itineraries, /api/reviews, /api/notifications, /api/operators, /api/admin.
• Database: persistent storage for users, operators, routes, schedules, bookings, payments, tickets, vouchers, promotions, Suki accounts, destinations, guides, itineraries, reviews, and notifications, seeded with demo data volumes defined in FR-129.
• Authentication Subsystem: dedicated authentication layer separated from business logic.
• Payments Subsystem: payment gateway abstraction with demo payment mode; supports GCash, Maya, credit card, debit card, online banking.
• Booking Subsystem, Loyalty Subsystem, Content Subsystem, and Analytics Subsystem, each logically separated per clean architecture.
• Integration Interfaces: airline APIs, bus operator APIs, ferry APIs, payment APIs, map APIs, weather APIs, and travel advisory APIs, with clearly labeled mock services when live sources are unavailable.
• QR / Ticket Validation: secure ticket identifier issuance and server-side validation service.

10.2 Non-Stack Constraints

No specific third-party frameworks are mandated by the source material; the stack must simply be a complete full-stack build with the layers above. The interface must not resemble a generic Bootstrap template, and the final product must not resemble a generic school project, basic CRUD app, static mockup, generic AI website, or simple landing page.

11. Assumptions and Constraints

1. Only transportation ticketing (Flights + Buses + Ferries) is the primary booking product; the platform is explicitly not an event ticketing marketplace.
2. The platform is focused on travelers in the Philippines with strong emphasis on Mindanao transportation, destinations, routes, affordable travel, repeat travelers, and local travel discovery.
3. Live transportation data may not be available at build time; clearly labeled demonstration data must be used until real provider APIs are connected.
4. Payment processing is architectural; no real processing may be claimed unless a real provider is connected. A demo payment mode must exist.
5. Travel alerts must only be real when connected to verified sources.
6. Destination popularity must never be stated as objective fact without verified tourism data; only dynamic rankings (Most Booked, Most Searched, Most Favorited, Trending, Traveler Favorites) are permitted.
7. All operators, voucher rules, Suki reward rules, and cancellation/refund rules are configurable.
8. Government ID details are only collected where required, and unnecessary sensitive information must never be requested.
9. Trip budget estimates must not imply they guarantee a complete trip.
10. Demo promo codes (WELCOME10, MINDANAO200, SUKIGOLD, WEEKEND150, FLYMINDA, FERRYFUN, BUSBUDDY) and demo prices must be clearly marked as demo content.
11. The platform must be built with clean architecture — separation of UI, business logic, API, database, authentication, payments, booking, loyalty, content, and analytics.
12. The final product must present as a commercial-grade Philippine travel startup, not as a school project, CRUD app, template, or mockup.

11.1 Sample Data References (Demo)

• Sample destinations: Cagayan de Oro, Camiguin, Bukidnon, Iligan, Davao City, Samal Island, Siargao, Surigao City, Zamboanga City, Lake Sebu, General Santos, Mati, Butuan, Dinagat Islands, Hinatuan, Bislig, Cotabato City, Pagadian, Ozamiz, Dipolog.
• Sample routes: CDO → Camiguin, CDO → Davao, CDO → Iligan, CDO → Butuan, CDO → Bukidnon, Davao → General Santos, Davao → Mati, Davao → Samal, Surigao → Siargao, Zamboanga → Basilan, Davao → Manila, CDO → Manila, CDO → Cebu, Siargao → Cebu, Davao → Cebu.
• Sample deals: Weekend Camiguin 15% OFF, CDO–Davao Bus Saver\x20\xe2\x82\xb1150 OFF, Siargao Adventure 10% OFF, Davao Flight Deal\x20\xe2\x82\xb1300 OFF, Suki Gold Special Extra 5% OFF (all fictional demo promotions until connected to real operators).
• Sample Suki account: Maria Santos — Gold, 4,250 points, 750 points to VIP, 3 vouchers, 18 completed trips.

12. Glossary

• MTTH: Mindanao Travel Ticketing Hub.
• SRD: System Requirements Document.
• Suki / Suki Traveler: The platform's loyalty program and its members. Core message: "The more you travel, the more you save."
• Suki Points: Loyalty points earned from completed bookings, eligible routes, promotions, referrals, reviews, birthday bonuses, first booking, and seasonal campaigns; never awarded for cancelled or fraudulent transactions.
• Suki Tiers: STARTER (0–999 points), PLUS (1,000–2,999 points), GOLD (3,000–5,999 points), VIP (6,000+ points).
• Digital Ticket: A professional digital boarding pass with a secure QR code identifier for bus, ferry, and flight tickets.
• QR Ticket Identifier: A secure token used in place of raw personal information, validated server-side for existence, ownership, validity, cancellation status, and check-in status.
• Promo Code: A configurable discount code (percentage, fixed, route-, operator-, destination-, transport-type-, minimum-spend-, first-booking-, or Suki-only).
• Voucher: A fixed or percentage travel credit with minimum booking requirements, expiration, usage limits, and eligibility rules.
• Flash Sale: A time-limited promotional card with original price, discounted price, discount percentage, countdown, and Book Deal CTA.
• Suki Dashboard: The traveler's view of tier, points, tier progress, available vouchers, completed trips, rewards, and earning opportunities.
• Trip Timeline: Booking Confirmed → Payment Completed → Ticket Issued → Travel Reminder → Boarding → Completed.
• Refund Lifecycle: Requested → Under Review → Approved → Processing → Completed, or Rejected.
• Route Explorer: "Where Can You Go From Here?" — transportation options from a selected city.
• Travel Planner: A /travel-planner wizard asking destination, dates, number of travelers, budget, and travel style.
• Itinerary Builder: A tool for creating multi-day itineraries with attached tickets, destinations, activities, notes, and budget.
• Digital Passport: A traveler feature that collects destination badges and tracks destinations visited.
• Trust Badges: Verified Operator, Secure Booking, Verified Ticket, Verified Traveler Review (no fake certifications).
• Multi-Transport Journey: Bus + Ferry, or Bus + Ferry + Flight journeys organized across multiple bookings.
• Demo Data: Clearly labeled sample destinations, routes, operators, schedules, users, bookings, tickets, vouchers, guides, reviews, and promotions used until live provider APIs are connected.
• Clean Architecture: Separation of UI, business logic, API, database, authentication, payments, booking, loyalty, content, and analytics — no single massive file or component.
• Project Name: silver-website — the user-chosen project identifier for the Mindanao Travel Ticketing Hub (MTTH) build.