Technical architecture

A modular monolith with an event-driven core

This prototype follows the build-ready pack: one deployable with clean module boundaries, coordinated through domain events rather than polling. Asset-light by design — no inventory, no fund-holding; escrow is an external licensed provider integrated via API.

Layered component view

Client / Presentation

Responsive web app (mobile-first) — traveller exchange, supply console, orders & wallet, admin

API surface

Versioned route handlers · live updates for pool size & price

Hero services

Pooling & Matching · Pricing Engine · Bidding / Auction

Application services

Identity & KYC · Trip / Demand · Offer & Order · Reputation · Notifications

Integration

Licensed escrow · KYC/AML · airline/GDS & hotel APIs (later)

Data

Transactional store · demand-data lake (aggregated, PDPL-gated) · event log

Service responsibilities

Identity & Access (+KYC): Users, roles, sessions, agency licence & KYC, PDPL consent
Trip / Demand: Create/edit trips; classify poolable vs instant; emits trip.posted
Pooling & Matching: Group similar trips; maintain live pool size; emits pool.updated
Pricing Engine: Descending price toward a supply-set floor; emits price.updated
Bidding / Auction: Structured bids on trip or pool; rank; close; emits bid.placed
Offer & Order: Winning bid → offer → order; escrow hold; fulfilment milestones
Escrow Integration: Thin adapter to a licensed provider: hold / release / refund
Reputation & Reviews: Post-trip reviews feeding the supplier trust score
Notifications: Event-triggered messages (price dropped, new bid, you won)
Demand-Data & Analytics: Aggregated, anonymised demand signals — PDPL-gated

Domain events (§2.2)

trip.posted: → matching, search index, demand-data
pool.updated: → pricing recompute, notifications
price.updated: → notifications to pool members
bid.placed: → ranking, notifications
auction.closed: → offer / order creation
order.funded: → fulfilment kickoff, billing
order.completed: → reviews, trust score, billing

Indicative API surface

POST /api/listings: Post a trip (pool or direct)
POST /api/listings/{id}/join: Join a pool
POST /api/listings/{id}/bids: Place a competing bid
POST /api/listings/{id}/select: Select winning bid → create order
POST /api/orders/{id}/escrow: Fund the licensed-escrow hold
POST /api/orders/{id}/milestone: Release a fulfilment milestone
POST /api/orders/{id}/review: Submit post-trip review
GET /api/events: Append-only domain event log

Live event stream

append-only audit log

The event-driven core (§2.2). Post a trip, join a pool or settle an order and watch the domain events land here.

No events yet — interact with the exchange to generate some.

Where the code lives

src/lib/pricing.tsPricing Engine — descending curve, floor-bounded
src/lib/store.tsTrip, Pooling, Bidding, Offer/Order, Escrow, Reviews
src/lib/events.tsEvent bus + append-only audit log
src/lib/types.tsData model (§4) — entities & relationships
src/app/api/**Versioned API surface — the only data surface the UI touches

The store is an in-memory stand-in for the Postgres transactional store + outbox. Because the UI only touches the API, that swap is isolated.