Web App

The Tripinger web app is the main public traveler-facing client for the platform. It is the first major product surface in the roadmap and is designed to help users discover destinations, search hotels and vehicles, plan trips, manage budgets, complete bookings, and participate in the platform’s social travel experience.

Purpose

This app serves tourists and local Sri Lankan travelers through a single browser-based experience. It connects the platform’s core modules into one journey: discovery, planning, booking, payment, trip management, and post-trip engagement.

Product scope

The startup blueprint defines the platform as an all-in-one travel and mobility system covering:

• hotel booking,
• vehicle rentals,
• food arrangements,
• itinerary planning,
• budget management,
• activities and experiences,
• reviews,
• social/community features,
• AI travel assistance,
• trust and safety flows.

The public web app is where most of those user journeys begin and where the MVP is expected to launch first. The roadmap prioritizes the web app before the mobile app and includes responsive design as a Phase 1 requirement.

Technology alignment

The blueprint recommends the following frontend choices for the public app:

MVP priorities

The roadmap lists the early build order for the platform. The public web app should support these Phase 1 priorities first:

1. User authentication with Google or email.
2. Hotel listing search.
3. Hotel booking and payment.
4. Tuk-tuk rental listing discovery.
5. Vehicle booking flow.
6. Basic itinerary builder.
7. Budget calculator.
8. Mobile-responsive layouts across core flows.

This means the web app should be built around actual conversion and trip-planning journeys, not just a marketing landing page.

Suggested traveler journeys

The app should support end-to-end traveler flows like these:

• Discover Sri Lanka destinations and categories.
• Search hotels by city, dates, budget, and amenities.
• Search vehicles by type, location, dates, and availability.
• View listing details with pricing, photos, features, and reviews.
• Build a trip draft with itinerary and budget estimates.
• Checkout using supported payment methods.
• Access bookings, saved trips, and account preferences.
• Leave reviews after verified stays or completed bookings.
• Participate in travel journals, posts, or destination community features as those modules launch.

Suggested folder structure

The exact code layout may evolve, but the app should be organized by product domains and reusable UI boundaries.

apps/web/
├─ src/
│  ├─ main.tsx
│  ├─ App.tsx
│  ├─ assets/
│  ├─ app/
│  │  ├─ providers/
│  │  ├─ router/
│  │  ├─ layouts/
│  │  └─ store/
│  ├─ components/
│  │  ├─ ui/
│  │  ├─ forms/
│  │  ├─ cards/
│  │  ├─ maps/
│  │  ├─ search/
│  │  ├─ booking/
│  │  ├─ planner/
│  │  ├─ budget/
│  │  ├─ social/
│  │  └─ feedback/
│  ├─ features/
│  │  ├─ auth/
│  │  ├─ home/
│  │  ├─ destinations/
│  │  ├─ hotels/
│  │  ├─ vehicles/
│  │  ├─ food/
│  │  ├─ activities/
│  │  ├─ planner/
│  │  ├─ budgets/
│  │  ├─ bookings/
│  │  ├─ payments/
│  │  ├─ reviews/
│  │  ├─ social/
│  │  ├─ profile/
│  │  └─ trips/
│  ├─ lib/
│  │  ├─ api/
│  │  ├─ auth/
│  │  ├─ config/
│  │  ├─ currency/
│  │  ├─ dates/
│  │  ├─ maps/
│  │  └─ utils/
│  ├─ hooks/
│  ├─ styles/
│  ├─ types/
│  └─ tests/
├─ public/
├─ index.html
└─ README.md

Main pages

Public routes

The MVP and near-term web app should expect pages or route groups like these:

• / — homepage and discovery entry point
• /search/hotels
• /search/vehicles
• /search/food
• /search/activities
• /hotels/:slug
• /vehicles/:slug
• /restaurants/:slug
• /activities/:slug
• /planner
• /budget
• /checkout
• /bookings
• /trips
• /profile
• /reviews
• /community
• /login
• /register

The exact URLs can change, but the information architecture should stay aligned with the product modules defined in the blueprint.

Homepage responsibilities

The homepage should do more than market the brand. It should act as a conversion surface that quickly routes users into high-intent actions such as hotel search, vehicle search, and trip planning. That matches the blueprint’s roadmap, which prioritizes transactional features very early in the build order.

Recommended homepage sections:

• hero with destination search entry,
• quick links for hotels, tuk-tuks, cars, bikes, and planners,
• featured destinations,
• featured hotels or rentals,
• trust signals,
• recent reviews or community content,
• app value proposition for both tourists and locals,
• CTA into plan-a-trip or book-now flows.

Search and listing experience

Search is central to the Tripinger concept because the platform combines multiple travel domains inside a single experience. The web app should present a consistent discovery pattern across hotels, vehicles, food, and later activities.

Shared search concerns:

• date selection,
• destination selection,
• availability filters,
• price range filters,
• category-specific filters,
• sorting,
• pagination or infinite scroll,
• saved searches,
• location context via maps,
• mobile-friendly filtering UX.

Domain-specific examples from the blueprint include hotel filters such as stars, eco-certified status, WiFi, pool, and beach, along with vehicle-type filters for tuk-tuks, bikes, scooters, cars, and driver preferences.

Booking flows

The public web app is expected to support real booking conversion early in the roadmap, especially for hotels and vehicle rentals. The booking experience should therefore be treated as a core product system, not as an afterthought.

Key booking steps:

1. Search and compare listings.
2. Review listing details and availability.
3. Choose dates, configuration, and add-ons.
4. Sign in or create an account if required.
5. Confirm price breakdown.
6. Pay using the supported checkout flow.
7. Receive booking confirmation and trip linkage.

The product blueprint ties booking activity into budgets, itineraries, reviews, and partner operations, so the web app should keep those transitions visible and intuitive.

Planner and budget modules

Trip planning and budget management are core differentiators in the blueprint, not side features. The public web app should let users draft itineraries, estimate trip costs, and connect those planning flows directly to search and booking actions.

Expected planner capabilities include:

• day-by-day itinerary drafting,
• route-aware trip structure,
• collaborative planning support,
• prebuilt travel circuits,
• booking-aware trip organization,
• AI-assisted itinerary generation in later phases.

Expected budget capabilities include:

• total budget input,
• category allocation,
• accommodation cost estimates,
• vehicle and food cost estimates,
• per-day budgeting,
• multi-currency presentation,
• export or share options in later phases.

Reviews and community

The blueprint positions reviews and user-generated content as a growth loop and trust engine for the platform. The web app should therefore be prepared to surface verified reviews, trip stories, destination content, and social engagement interfaces as the roadmap expands beyond MVP.

Community-oriented UI areas may include:

• traveler reviews,
• trip journals,
• destination feed,
• local tips,
• saved posts,
• traveler profile activity,
• follow and engagement surfaces,
• content moderation states.

Auth and account flows

The blueprint calls for JWT and OAuth 2.0 support, including Google, Facebook, and Apple login options, which means the web app should support both password-based and social onboarding paths.

Common account flows:

• register,
• login,
• social sign-in,
• email verification,
• forgot password,
• reset password,
• profile update,
• traveler preferences,
• saved items,
• bookings and trip history.

Environment variables

This app should read only public-safe Vite variables in the browser. Typical variables include:

• VITE_APP_NAME
• VITE_APP_ENV
• VITE_API_BASE_URL
• VITE_WEB_BASE_URL
• VITE_MAPBOX_ACCESS_TOKEN
• VITE_STRIPE_PUBLISHABLE_KEY
• VITE_PAYHERE_MERCHANT_ID
• VITE_FEATURE_AI_PLANNER
• VITE_FEATURE_BUDGET_MANAGER
• VITE_FEATURE_SOCIAL_FEED
• VITE_FEATURE_FOOD_MODULE

Use the root .env.example as the canonical variable reference.

Local development

Prerequisites

Install:

• Node.js LTS
• pnpm
• access to the root .env file
• the Tripinger API running locally
• Docker if supporting services are started through containers

Typical setup

pnpm install
cp .env.example .env
pnpm docker:up
pnpm --filter web dev

If the monorepo uses root-level commands for workspace orchestration, prefer those.

Expected local URLs

Web app:   http://localhost:3000
API:       http://localhost:4000/api/v1
API docs:  http://localhost:4000/docs

Styling guidance

The blueprint recommends Tailwind CSS for rapid, consistent UI development and Framer Motion for smooth user experience transitions. The public web app should use those tools to create a clean, mobile-friendly booking interface rather than a purely decorative marketing site.

UI priorities should include:

• clear search forms,
• trustworthy pricing and booking summaries,
• readable mobile cards,
• fast-loading listing grids,
• accessible forms,
• responsive sticky booking panels where useful,
• smooth but restrained animation,
• multilingual readiness for future Sinhala and Tamil rollout.

Maps and location UX

Mapbox is part of the planned stack, so the web app should use location-aware experiences where they add genuine value. Strong candidates include:

• hotel and vehicle map views,
• destination browsing,
• route previews for planners,
• pickup and drop-off context,
• city or region discovery,
• later support for safety or itinerary geography features.

State and data fetching

The exact data layer is not yet locked, but the app should treat API data as domain-specific, cacheable, and query-driven. A structured client layer is recommended for:

• auth session state,
• search query state,
• listing detail fetching,
• booking mutation flows,
• planner drafts,
• budget calculations,
• profile data,
• notifications and saved content.

Recommended principles:

• keep server state separate from local UI state,
• co-locate queries with features where practical,
• normalize date and currency handling,
• centralize API error formatting,
• handle loading, empty, and failure states intentionally.

Testing expectations

At minimum, the web app should support:

• component tests,
• route-level integration tests,
• form validation tests,
• booking-flow tests,
• auth-flow tests,
• responsive UI checks on key pages.

Highest-priority test flows for Phase 1:

1. Homepage search entry.
2. Hotel search and filter flow.
3. Hotel detail to checkout path.
4. Vehicle search to booking request path.
5. Planner draft creation.
6. Budget calculator interaction.
7. Login and registration flow.

Deployment direction

The blueprint positions the web frontend on Vercel early and later within a broader AWS-backed architecture as the platform scales. The web app should therefore remain easy to deploy as a standalone frontend, with environment-based configuration and API-driven behavior.

Recommended deployment properties:

• static asset optimization,
• route fallback handling,
• environment-specific API base URLs,
• error tracking hooks,
• analytics hooks when enabled,
• image performance awareness,
• SEO-ready metadata for destination and listing pages.

Contribution guidance

When adding a new traveler-facing feature:

1. Place it under src/features/<domain>.
2. Keep reusable presentation components inside src/components.
3. Add or update route definitions in the router layer.
4. Keep API calls in shared client helpers or feature-specific services.
5. Add loading, empty, and error states.
6. Ensure the experience works on mobile widths.
7. Document any new public env variables in the root .env.example.
8. Update this README if the feature changes app-level structure.

Current status

This README captures the intended operating model for the Tripinger public web app based on the startup blueprint and approved Phase 1 architecture work. Exact commands, package choices, and route implementations should be aligned with the actual repository once scaffolding is in place.