Skip to content

svc-reservations

Reservations Service  |  Booking  |  v2.4.1  |  NovaTrek Platform Team

Manages adventure trip reservations for NovaTrek Adventures.

Swagger UI Download OpenAPI Spec

Integration Context

⤢svc-reservations C4 context diagram

Data Store

Overview

Property Detail
Engine PostgreSQL 15
Schema reservations
Tables reservations, participants, status_history
Estimated Volume ~2,000 new reservations/day
Connection Pool min 10 / max 40 / idle timeout 10min
Backup Strategy Continuous WAL archiving, daily base backup, 30-day PITR

Key Features

  • Optimistic locking via _rev field
  • Composite index on (guest_id, trip_date)
  • Monthly partitioning by reservation_date

Table Reference

reservations

Core reservation records for adventure bookings

Column Type Constraints
reservation_id UUID PK
guest_id UUID NOT NULL
trip_id UUID NOT NULL
confirmation_code VARCHAR(12) NOT NULL, UNIQUE
status VARCHAR(20) NOT NULL, DEFAULT 'confirmed'
trip_date DATE NOT NULL
party_size INTEGER NOT NULL, CHECK (> 0)
total_amount DECIMAL(10,2) NOT NULL
currency CHAR(3) NOT NULL, DEFAULT 'USD'
_rev INTEGER NOT NULL, DEFAULT 1
created_at TIMESTAMPTZ NOT NULL
updated_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_res_guest_date on guest_id, trip_date
  • idx_res_trip_date on trip_id, trip_date
  • idx_res_confirmation on confirmation_code (UNIQUE)
  • idx_res_status on status

participants

Individual participants linked to a reservation

Column Type Constraints
participant_id UUID PK
reservation_id UUID NOT NULL, FK -> reservations
guest_id UUID NOT NULL
role VARCHAR(20) NOT NULL, DEFAULT 'guest'
waiver_signed BOOLEAN NOT NULL, DEFAULT FALSE
created_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_part_reservation on reservation_id
  • idx_part_guest on guest_id

status_history

Audit trail of reservation status transitions

Column Type Constraints
history_id UUID PK
reservation_id UUID NOT NULL, FK -> reservations
old_status VARCHAR(20) NULL
new_status VARCHAR(20) NOT NULL
changed_by VARCHAR(100) NOT NULL
reason TEXT NULL
changed_at TIMESTAMPTZ NOT NULL, DEFAULT NOW()

Indexes:

  • idx_hist_reservation on reservation_id, changed_at DESC

Solutions Affecting This Service

Ticket Solution Capabilities Date
NTK-10008 Guest Reviews and Ratings Platform CAP-1.7, CAP-1.2 2026-03-06
NTK-10009 Refund and Dispute Management Workflows CAP-5.5, CAP-5.4 2026-03-06

Endpoints (8 total)

GET /reservations -- Search reservations

Returns a paginated list of reservations matching the given criteria.

View in Swagger UI

⤢GET /reservations sequence diagram

POST /reservations -- Create a new reservation

Creates a new adventure reservation. Validates guest eligibility,

View in Swagger UI

⤢POST /reservations sequence diagram

GET /reservations/{reservation_id} -- Get reservation details

View in Swagger UI

⤢GET /reservations/{reservation_id} sequence diagram

PATCH /reservations/{reservation_id} -- Update a reservation

Partially updates a reservation. Only modifiable fields can be changed.

View in Swagger UI

⤢PATCH /reservations/{reservation_id} sequence diagram

DELETE /reservations/{reservation_id} -- Cancel a reservation

View in Swagger UI

⤢DELETE /reservations/{reservation_id} sequence diagram

GET /reservations/{reservation_id}/participants -- Get reservation participants

View in Swagger UI

⤢GET /reservations/{reservation_id}/participants sequence diagram

POST /reservations/{reservation_id}/participants -- Add a participant to a reservation

View in Swagger UI

⤢POST /reservations/{reservation_id}/participants sequence diagram

PUT /reservations/{reservation_id}/status -- Transition reservation status

Explicitly transitions a reservation to a new status.

View in Swagger UI

⤢PUT /reservations/{reservation_id}/status sequence diagram

Consuming Applications

Application Screens Using This Service
Guest Portal Booking Flow, Guest Profile, Reservation Management, Trip Gallery
Operations Dashboard Check-In Station, Transport Dispatch, Analytics Dashboard, Partner Bookings
Adventure App Self Check-In, My Reservations, Earn Loyalty Points

Events Published

Event Channel Trigger Consumers
reservation.created novatrek.booking.reservation.created POST /reservations svc-scheduling-orchestrator, svc-analytics
reservation.status_changed novatrek.booking.reservation.status-changed PUT /reservations/{reservation_id}/status svc-notifications, svc-analytics

Events Consumed

Event Producer Channel
payment.processed svc-payments novatrek.support.payment.processed