Architecture

Table of Contents

• Document Purpose
• Architecture Overview
• Product Surfaces
• Core Architecture Principles
• Logical System Context
• Service Landscape
• Domain Boundaries
• Primary Workflows
• Data Flow Overview
• Integration Architecture
• Deployment Topology
• Scalability Strategy
• Security Architecture
• Observability and Operations
• Environment View
• Architecture Decisions Pending Confirmation
• Assumptions

Document Purpose

This document describes the planned high-level system architecture for Tripinger. It defines the major applications, service boundaries, data flow patterns, integrations, infrastructure direction, and operational concerns for the platform.

This is an architecture planning document, not an assertion that all components are already implemented. Where exact technical decisions are still unconfirmed, explicit placeholders or assumptions are used.

Architecture Overview

Tripinger is planned as a multi-application travel platform for Sri Lanka, serving tourists, local travelers, partners, and internal operations teams through a shared backend architecture. The product combines accommodation booking, vehicle rentals, activities, food arrangements, AI trip planning, budget management, reviews, community features, partner operations, and admin workflows in a single ecosystem.

The current architecture direction is a modular, service-oriented platform with a central API entry layer, separate frontend applications, shared data services, and external integrations for payments, messaging, storage, AI, and mapping. The investor blueprint also indicates async processing for notification and booking-related workflows, plus caching and search infrastructure for scale.

Product Surfaces

Tripinger currently assumes four main application surfaces in the monorepo:

Assumption: Mobile applications are planned for a later stage and are not treated as first-class repository surfaces in the current Phase 1 documentation set.

Core Architecture Principles

The platform architecture is designed around the following principles:

1. Single product, multiple surfaces
   One business domain is exposed through specialized applications for travelers, partners, and administrators.

2. Modular backend design
   Business capabilities are separated into bounded domains such as auth, users, hotels, vehicles, bookings, payments, reviews, notifications, partners, search, and AI planning.

3. API-first interaction model
   All clients interact through documented backend APIs rather than embedding business rules in frontend applications.

4. Asynchronous side effects
   Non-blocking workflows such as notifications, confirmation emails, search indexing, payout generation, and some booking events should be handled asynchronously where possible.

5. Transactional core + specialized supporting stores
   Structured business records remain in the primary relational database, while caching, search, and optional flexible-content workloads are delegated to specialized infrastructure.

6. Progressive scalability
   The initial implementation should remain operationally simple, while preserving a path to split scaling concerns as traffic, partner volume, and data complexity grow.

Logical System Context

Tripinger sits between demand-side users, supply-side partners, internal operations, and several external services.

External actors

• Travelers
• Local Sri Lankan users
• Hotel partners
• Vehicle owners and operators
• Experience and food partners
• Internal admin and support teams

External systems

• PayHere for local payments
• Stripe for international payments
• Email delivery provider
• SMS and/or WhatsApp messaging provider
• Map and geolocation provider
• Object/media storage provider
• AI provider for itinerary and assistant capabilities
• Search infrastructure
• Optional analytics, monitoring, and error tracking services

Service Landscape

The current architecture is best represented as a modular backend inside a shared platform boundary. The service map below expresses the planned logical layout; whether these modules run as one deployable NestJS application or evolve into independently deployable services remains a later implementation decision.

Domain Boundaries

The main planned backend domains are listed below.

Primary Workflows

1. Traveler booking journey

1. Traveler searches accommodations, vehicles, or experiences.
2. Search module serves ranked/filterable results.
3. User selects inventory and initiates booking.
4. Booking module validates availability, pricing, and booking rules.
5. Payment module creates transaction with the relevant payment provider.
6. On successful payment confirmation, booking state is updated.
7. Notification workflows send confirmations to the user and partner.
8. Downstream systems receive async updates for dashboards, analytics, and search freshness.

2. Partner onboarding journey

1. Partner registers via partner portal.
2. Auth and partner modules create an account and pending partner profile.
3. Verification documents are uploaded and stored.
4. Admin reviews documents and verification state.
5. Upon approval, partner receives access to relevant listing and payout features.

3. AI planning journey

1. Traveler provides destination, duration, budget, and preferences.
2. AI planner normalizes request data and enriches it with available product context.
3. Planner requests itinerary generation from the AI layer.
4. Generated itineraries may be linked back to hotels, vehicles, and experiences.
5. User can save, revise, or convert itinerary items into bookings.

4. Admin moderation and operations journey

1. Admin user authenticates into the admin dashboard.
2. Admin module exposes role-limited access to reviews, partners, payouts, support, and reports.
3. Sensitive actions are logged for audit and operational traceability.

Data Flow Overview

The architecture uses a hybrid flow model:

• Synchronous request/response for user-facing API operations such as login, profile fetch, search requests, booking initiation, and dashboard reads.
• Asynchronous event-driven processing for side effects such as email confirmations, search indexing, payout preparation, notification fan-out, and some reconciliation flows.

Data storage roles

Assumption: The earlier blueprint referenced MongoDB for flexible data such as reviews and social content. The current approved 79-file documentation plan only defines PostgreSQL-based database documentation modules, so PostgreSQL is treated as the canonical documented source of truth until a separate polyglot persistence decision is explicitly approved.

Integration Architecture

Tripinger depends on several third-party systems.

Integration pattern

• External providers should be wrapped behind service adapters.
• Provider-specific DTOs and webhook handlers should remain isolated from domain logic.
• The payment layer must be designed so that booking state transitions are driven by verified payment outcomes, not only frontend callbacks.

Deployment Topology

Tripinger is currently planned for containerized deployment with a split between frontend delivery and backend/service hosting.

Planned infrastructure direction

• Frontend surfaces may be deployed through an edge-friendly hosting platform.
• Backend services are expected to run in containerized environments.
• PostgreSQL is the primary system of record.
• Redis and search infrastructure are introduced as scaling and feature needs justify them.
• Background workers handle non-request-critical workloads.

Assumption: Early-stage deployments may consolidate several concerns into fewer runtime units for simplicity, even if the long-term documentation describes them separately.

Scalability Strategy

The architecture is intended to scale progressively rather than start with maximum operational complexity.

Early-stage strategy

• Keep the API modular but operationally consolidated.
• Start with one primary relational database.
• Use caching selectively for high-read workflows.
• Add search indexing only where discovery quality requires it.
• Keep worker infrastructure small and focused on essential async tasks.

Growth-stage strategy

• Scale frontend surfaces independently from the API.
• Introduce horizontal scaling for API workloads.
• Add read replicas and stronger queue-backed async processing if booking load grows.
• Increase search index sophistication for destination-aware and relevance-aware discovery.
• Separate AI workloads from core request-handling capacity.

Scale-stage strategy

• Split high-traffic or high-risk modules into more isolated deployable services if justified.
• Use stronger event-driven orchestration for payments, notifications, and reporting.
• Introduce more formalized rate limiting, traffic shaping, and cost controls around AI workloads.

Security Architecture

Tripinger handles identity, payments, partner verification data, and user-generated content, so the architecture must enforce strong separation of concerns.

Security model

• Centralized authentication and authorization.
• Role-based access control for admin and partner functionality.
• Sensitive operations restricted to server-side enforcement.
• Payment provider webhooks verified before booking/payment state changes.
• Partner documents and media stored with controlled access patterns.
• Auditability for moderation, payouts, and privileged admin actions.

Security-sensitive areas

• Authentication tokens and refresh flows
• Payment webhooks and transaction verification
• Partner identity and banking details
• Review moderation and abuse controls
• Admin access boundaries
• AI prompt and output handling where user or booking data is involved

See also:

• SECURITY.md
• apps/api/docs/AUTH.md
• apps/api/docs/API_CONVENTIONS.md

Observability and Operations

The architecture should support operational visibility from the start, especially across booking, payment, and notification workflows.

Required operational signals

• API health and latency
• Booking creation and failure rates
• Payment success, failure, refund, and webhook reconciliation events
• Notification delivery success/failure
• Search indexing lag or failures
• Partner onboarding pipeline health
• AI request volume, latency, and cost trends

Logging direction

• Structured application logs
• Error tracking with request context where safe
• Event logs for operational workflows
• Separate audit logging for privileged internal actions

Detailed monitoring and backup procedures will be defined in later Phase 3 documents.

Environment View

Tripinger is expected to operate across at least four environments.

Environment-specific details will be documented in docs/ENVIRONMENTS.md and docs/DEVOPS.md.

Architecture Decisions Pending Confirmation

The following architecture decisions are not yet fully confirmed:

1. Whether the backend starts as a single modular NestJS application or multiple independently deployable services.
2. Whether MongoDB remains part of the final production architecture for social/community or flexible content domains.
3. Which queue/event transport is selected for asynchronous workloads.
4. Whether WebSocket infrastructure is required in Phase 1 or introduced later.
5. Final hosting split between Vercel, AWS ECS, or a hybrid deployment approach.
6. Whether the AI planner remains embedded in the main API boundary or becomes a dedicated service earlier.
7. Final CDN and media-delivery strategy.

Assumptions

• Assumption: apps/api is the main backend platform and acts as the principal API boundary in the monorepo.
• Assumption: Search, Redis, and worker infrastructure are part of the intended architecture even if introduced progressively.
• Assumption: PostgreSQL is the documented primary database unless a later approved decision adds a second persistent datastore.
• Assumption: Admin and partner portals use the same backend platform with domain-based authorization boundaries rather than separate backend stacks.
• Assumption: Booking, payment, and notification flows are core enough to justify dedicated domain modules from the beginning of implementation planning.