Skip to content

svc-guide-management

NovaTrek Guide Management Service  |  Guide Management  |  v2.4.0  |  NovaTrek Platform Engineering

Manages adventure guides for NovaTrek Adventures, including guide profiles,

Swagger UI Download OpenAPI Spec Live Service (Dev) Azure Portal CI/CD Pipeline Source Code Technology Stack

Delivery Status

Delivery Wave: 4 -- Guide and Transport Operations

Stage Status
Infrastructure (Bicep) ✅ complete
Database Schema (Flyway) ✅ complete
Deployed to Dev ✅ complete
Smoke Tested ✅ complete
Deployed to Prod not-started
Pipeline Status
CI Pipeline ✅ complete
CD Pipeline ✅ complete

Azure Resources (Dev):

Integration Context

⤢svc-guide-management C4 context diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml + cross-service-calls.yaml

Data Store

Entity Relationship Diagram

⤢svc-guide-management entity relationship diagram

⚙ Generated from architecture/metadata/data-stores.yaml

Overview

Property Detail
Engine PostgreSQL 15
Schema guides
Tables guides, certifications, guide_schedules, availability_windows, ratings
Estimated Volume ~100 schedule updates/day, ~500 availability queries/day
Connection Pool min 3 / max 15 / idle timeout 10min
Backup Strategy Daily pg_dump, 30-day retention

Key Features

  • Certification expiry tracking with automated alerts
  • Availability window overlap detection constraints
  • Weighted rating aggregation with recency bias

Table Reference

guides

Adventure guide profiles and qualifications

Column Type Constraints
guide_id UUID PK
first_name VARCHAR(100) NOT NULL
last_name VARCHAR(100) NOT NULL
email VARCHAR(255) NOT NULL, UNIQUE
phone VARCHAR(30) NOT NULL
hire_date DATE NOT NULL
status VARCHAR(20) NOT NULL, DEFAULT 'active'
avg_rating DECIMAL(3,2) NULL
total_trips INTEGER NOT NULL, DEFAULT 0

Indexes:

  • idx_guide_email on email (UNIQUE)
  • idx_guide_status on status
  • idx_guide_rating on avg_rating DESC NULLS LAST

certifications

Guide adventure certifications with expiry tracking

Column Type Constraints
cert_id UUID PK
guide_id UUID NOT NULL, FK -> guides
cert_type VARCHAR(50) NOT NULL
level VARCHAR(20) NOT NULL
issued_date DATE NOT NULL
expiry_date DATE NOT NULL
verified BOOLEAN NOT NULL, DEFAULT FALSE

Indexes:

  • idx_gcert_guide on guide_id
  • idx_gcert_expiry on expiry_date

availability_windows

Time blocks when a guide is available for scheduling

Column Type Constraints
window_id UUID PK
guide_id UUID NOT NULL, FK -> guides
start_time TIMESTAMPTZ NOT NULL
end_time TIMESTAMPTZ NOT NULL
recurrence VARCHAR(20) NULL

Indexes:

  • idx_avail_guide_time on guide_id, start_time

ratings

Guest ratings and reviews for guides

Column Type Constraints
rating_id UUID PK
guide_id UUID NOT NULL, FK -> guides
guest_id UUID NOT NULL
trip_id UUID NOT NULL
score SMALLINT NOT NULL, CHECK (1-5)
comment TEXT NULL
rated_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_rating_guide on guide_id, rated_at DESC

Endpoints (12 total)

GET /guides -- Search guides with filters

Returns a paginated list of guides matching the specified filter criteria.

View in Swagger UI

⤢GET /guides sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

POST /guides -- Create a new guide profile

Registers a new adventure guide in the system.

View in Swagger UI

⤢POST /guides sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/{guide_id} -- Get guide by ID

Retrieves the full profile for a specific guide.

View in Swagger UI

⤢GET /guides/{guide_id} sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

PATCH /guides/{guide_id} -- Update guide profile

Partially updates a guide profile. Only provided fields are modified.

View in Swagger UI

⤢PATCH /guides/{guide_id} sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/{guide_id}/certifications -- List guide certifications

Returns all certifications held by the specified guide.

View in Swagger UI

⤢GET /guides/{guide_id}/certifications sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

POST /guides/{guide_id}/certifications -- Add a certification to a guide

Records a new certification for the specified guide.

View in Swagger UI

⤢POST /guides/{guide_id}/certifications sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/{guide_id}/schedule -- Get upcoming trip assignments

Returns the guide's upcoming scheduled trip assignments.

View in Swagger UI

⤢GET /guides/{guide_id}/schedule sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/{guide_id}/availability -- Get guide availability windows

Returns the availability windows configured for this guide.

View in Swagger UI

⤢GET /guides/{guide_id}/availability sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

POST /guides/{guide_id}/availability -- Set availability windows

Creates or updates availability windows for the guide.

View in Swagger UI

⤢POST /guides/{guide_id}/availability sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/{guide_id}/ratings -- Get guest ratings and reviews

Returns paginated guest ratings and reviews for the specified guide.

View in Swagger UI

⤢GET /guides/{guide_id}/ratings sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

POST /guides/{guide_id}/ratings -- Submit a guest rating

Records a guest rating and optional review for a guide.

View in Swagger UI

⤢POST /guides/{guide_id}/ratings sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

GET /guides/available -- Find available guides for a date, activity, and region

Searches for guides who are available on the specified date, hold relevant

View in Swagger UI

⤢GET /guides/available sequence diagram

⚙ Generated from architecture/specs/svc-guide-management.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.

Consuming Applications

Application Screens Using This Service
Operations Dashboard Daily Schedule Board, Guide Assignment, Safety Incident Board

Events Consumed

Event Producer Channel
schedule.published svc-scheduling-orchestrator novatrek.operations.schedule.published