API Overview

The Tripinger API powers the core backend for the platform’s travel marketplace, booking engine, partner workflows, AI-enabled planning, and community features. It is designed around NestJS, TypeScript, and a modular domain-driven structure so the backend can launch quickly as a maintainable application and later evolve into independently scalable services as demand grows.

Purpose

This API is the system of record and orchestration layer for the Tripinger platform. It serves the public web application, admin dashboard, partner portal, and future mobile clients across domains such as hotels, vehicle rentals, food arrangements, itinerary planning, payments, notifications, reviews, and social/community experiences.

Architecture direction

The product blueprint recommends Node.js with NestJS for the backend and describes an API Gateway plus independently scalable domain services for booking, rental, hotel, food, social, AI, and realtime functionality. The practical implementation approach for Phase 1 is to keep those boundaries clean inside a NestJS codebase, even if the first release is deployed as a modular monolith before service extraction.

Design principles

• Keep business domains isolated by module.
• Treat PostgreSQL as the source of truth for transactional records.
• Use Redis for cache and short-lived coordination.
• Use Elasticsearch as a derived search layer.
• Use MongoDB only for flexible document-oriented content if retained for the chosen release scope.
• Prefer async workflows for notifications, indexing, and background processing.
• Keep payment, booking, and ledger-related actions explicit and auditable.
• Design the API for web, admin, partner, and mobile consumers from day one.

Core domains

The platform blueprint defines a broad product surface, so the backend is expected to cover the following business modules:

• Auth and users
• Profiles and traveler preferences
• Hotels and rooms
• Vehicle rentals, including tuk-tuks, bikes, and cars
• Food and restaurant arrangements
• Activities and experiences
• Itinerary planner and budget manager
• Bookings and availability
• Payments and payout preparation
• Reviews and ratings
• Social feed, posts, and trip journals
• Notifications
• Search
• Media
• Partner operations
• Admin operations
• Safety, compliance, and verification
• AI assistant and recommendation workflows

Suggested folder structure

The exact structure may evolve, but the API should be organized by domain rather than by technical layer alone.

apps/api/
├─ src/
│  ├─ main.ts
│  ├─ app.module.ts
│  ├─ common/
│  │  ├─ constants/
│  │  ├─ decorators/
│  │  ├─ dto/
│  │  ├─ exceptions/
│  │  ├─ filters/
│  │  ├─ guards/
│  │  ├─ interceptors/
│  │  ├─ pipes/
│  │  ├─ utils/
│  │  └─ types/
│  ├─ config/
│  │  ├─ app/
│  │  ├─ auth/
│  │  ├─ cache/
│  │  ├─ database/
│  │  ├─ mail/
│  │  ├─ payments/
│  │  ├─ search/
│  │  ├─ storage/
│  │  └─ validation/
│  ├─ modules/
│  │  ├─ auth/
│  │  ├─ users/
│  │  ├─ profiles/
│  │  ├─ hotels/
│  │  ├─ vehicles/
│  │  ├─ food/
│  │  ├─ activities/
│  │  ├─ planner/
│  │  ├─ budgets/
│  │  ├─ bookings/
│  │  ├─ payments/
│  │  ├─ payouts/
│  │  ├─ reviews/
│  │  ├─ social/
│  │  ├─ notifications/
│  │  ├─ search/
│  │  ├─ media/
│  │  ├─ partners/
│  │  ├─ admin/
│  │  ├─ compliance/
│  │  └─ ai/
│  ├─ integrations/
│  │  ├─ openai/
│  │  ├─ payhere/
│  │  ├─ stripe/
│  │  ├─ sendgrid/
│  │  ├─ twilio/
│  │  ├─ firebase/
│  │  ├─ mapbox/
│  │  ├─ s3/
│  │  └─ search/
│  └─ jobs/
│     ├─ queues/
│     ├─ processors/
│     └─ schedulers/
├─ test/
├─ prisma/
├─ uploads/
└─ README.md

This structure keeps business logic grouped by domain while still allowing shared infrastructure, integrations, and background processing to remain reusable and centrally managed.

Main responsibilities

Public traveler APIs

These endpoints power search, discovery, availability, booking, payments, itinerary planning, budget tracking, reviews, and traveler account actions. They support both international tourists and local Sri Lankan travelers, which is a core product position in the blueprint.

Partner APIs

These endpoints let hotels, vehicle owners, restaurant partners, guides, and other providers manage listings, availability, pricing, bookings, verification status, and operational responses. The blueprint explicitly depends on partner onboarding and supply-side participation, especially for hotels and vehicle owners.

Admin APIs

These endpoints support moderation, verification, reporting, platform operations, dispute handling, partner approval, payout review, content control, and platform analytics. This is necessary because the product includes verified listings, trust workflows, and operational oversight across multiple booking surfaces.

Internal workflows

The backend also coordinates asynchronous jobs such as search indexing, booking confirmations, reminders, notification dispatch, review eligibility checks, AI enrichment tasks, and possible escrow or payout lifecycle handling. The blueprint specifically calls for event-driven async operations and Redis-backed coordination to prevent overload during peak demand.

Technology alignment

The API is expected to align with the following stack choices from the platform blueprint:

Local development

Prerequisites

Install the following before running the API locally:

• Node.js LTS
• pnpm
• Docker and Docker Compose
• PostgreSQL, or run it through Docker
• Redis, or run it through Docker
• MongoDB if included in the current release scope
• Elasticsearch or OpenSearch-compatible local service if search is enabled
• Access to a local .env file based on the project’s .env.example

Typical setup flow

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

If the monorepo uses root-level scripts, prefer those instead of invoking the API package directly.

Database setup

The relational database should be initialized before running booking and auth flows because the platform’s core entities depend on structured transactional storage. PostgreSQL is the intended source of truth for users, bookings, payments, listings, and operational records.

Typical setup may look like:

pnpm db:generate
pnpm db:migrate
pnpm db:seed

Replace these commands with the exact workspace scripts once they are finalized.

Environment variables

The API depends on shared and service-specific environment variables such as:

• DATABASE_URL
• REDIS_URL
• MONGODB_URI
• ELASTICSEARCH_NODE
• JWT_ACCESS_SECRET
• JWT_REFRESH_SECRET
• OPENAI_API_KEY
• PAYHERE_MERCHANT_ID
• STRIPE_SECRET_KEY
• AWS_S3_BUCKET
• SENDGRID_API_KEY
• TWILIO_ACCOUNT_SID
• FIREBASE_PROJECT_ID
• MAPBOX_ACCESS_TOKEN

Use the root .env.example as the canonical reference for local development.

API documentation

Because the platform serves multiple clients and contains a broad surface area, interactive API documentation should be enabled in development and staging environments. Swagger or OpenAPI documentation is strongly recommended for:

• endpoint discovery,
• DTO validation visibility,
• auth flow testing,
• partner integration support,
• admin tooling alignment, and
• future mobile client consumption.

Typical development URL:

http://localhost:4000/docs

Authentication and authorization

The blueprint calls for JWT and OAuth 2.0 support with Google, Facebook, and Apple login options. The API should therefore separate identity, session handling, role enforcement, and resource authorization cleanly from business modules.

Suggested access roles:

• Traveler
• Partner
• Hotel Partner
• Vehicle Owner
• Restaurant Partner
• Guide or Activity Partner
• Admin
• Super Admin
• Support Agent

Authorization should support both role-based access control and resource ownership rules. For example, a hotel partner should only access their own properties and bookings, while platform admins may access moderation and compliance workflows across all tenants.

Module notes

Auth

Supports email/password, OAuth login, token refresh, password reset, and account verification. It is foundational because all booking, review, partner, and admin workflows depend on trusted identity.

Hotels

Handles listings, rooms, amenities, availability, pricing, verified badges, and hotel booking integration. The blueprint makes hotels a core revenue driver and emphasizes independent hotel onboarding with lower commission than global OTAs.

Vehicles

Supports tuk-tuk, bike, scooter, bicycle, and car listings, owner onboarding, document verification, availability, pricing, pickup/return workflows, and potential escrow-related coordination. This is one of the platform’s strongest differentiators in the blueprint.

Food

Handles destination-based discovery, restaurant listings, table reservations, food trails, hotel meal add-ons, and dietary filters. The blueprint positions this as a tourist-oriented arrangement layer rather than a general food-delivery product.

Planner and budgets

Handles itinerary generation, collaborative planning, route-aware trip structure, and spend estimation or tracking. The blueprint describes these modules as deeply integrated with hotels, vehicles, food, and AI assistance.

Reviews and social

Supports verified reviews, social posting, trip journals, destination content, and possibly engagement or moderation workflows. The blueprint treats user-generated content as a strategic moat for retention, SEO, and trust.

Payments

Coordinates checkout, provider-specific payment flows, webhook validation, refund handling, and booking-payment linkage. The blueprint plans to use PayHere for local currency flows and Stripe for international payments.

AI

Supports itinerary generation, travel assistance, recommendations, and possibly review summarization or sentiment workflows. The blueprint explicitly includes OpenAI-powered itinerary generation and assistant features, plus a separate Python recommendation service.

Background jobs

Some operations should not block the request-response cycle. The following are good queue candidates:

• booking confirmation emails,
• payment receipt emails,
• SMS or WhatsApp notifications,
• push notifications,
• search index updates,
• media processing,
• review eligibility updates,
• recommendation refreshes,
• AI post-processing,
• scheduled reminders before check-in, pickup, or reservations.

Testing guidance

At minimum, the API should support:

• unit tests for services and guards,
• integration tests for modules and repositories,
• e2e tests for critical flows,
• webhook tests for PayHere and Stripe,
• auth flow tests,
• booking lifecycle tests,
• partner permission tests.

Priority e2e flows for Phase 1:

1. User registration and login.
2. Hotel search and booking.
3. Vehicle listing search and booking request.
4. Payment intent creation and webhook confirmation.
5. Partner login and listing update.
6. Admin verification action.
7. Planner creation linked to a booking or trip draft.

Operational expectations

The blueprint recommends Docker, GitHub Actions, Vercel, AWS ECS, and event-driven processing for growth. The API should therefore be designed to run cleanly in containers, expose health endpoints, and keep secrets externalized through environment configuration.

Recommended operational additions:

• /health
• /health/live
• /health/ready
• structured JSON logging
• request IDs
• audit logging for payment and admin actions
• rate limiting for auth and booking endpoints
• idempotency for webhook handlers and booking confirmation paths

Contribution guidance

When adding a new domain module:

1. Create the module inside src/modules.
2. Define DTOs, controllers, services, and persistence boundaries inside the module.
3. Reuse shared validation, guards, and exception patterns from src/common.
4. Register configuration needs explicitly.
5. Add tests for service logic and at least one end-to-end path.
6. Document new environment variables in the root .env.example.
7. Update this README if the module changes platform-level architecture.

Current status

This README defines the intended structure and operating model for the Tripinger backend API based on the approved foundation documents and the startup blueprint. Exact commands, package names, folder paths, and scripts should be aligned with the actual repository once scaffolding is committed.