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

Integration Context¶

Data Store¶

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

POST `/guides` -- Create a new guide profile¶

Registers a new adventure guide in the system.

View in Swagger UI

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

Retrieves the full profile for a specific guide.

View in Swagger UI

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

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

View in Swagger UI

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

Returns all certifications held by the specified guide.

View in Swagger UI

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

Records a new certification for the specified guide.

View in Swagger UI

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}/availability` -- Get guide availability windows¶

Returns the availability windows configured for this guide.

View in Swagger UI

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

Creates or updates availability windows for the guide.

View in Swagger UI

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

Returns paginated guest ratings and reviews for the specified guide.

View in Swagger UI

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

Records a guest rating and optional review for a guide.

View in Swagger UI

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

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`