Skip to content

svc-scheduling-orchestrator

NovaTrek Scheduling Orchestrator API  |  Operations  |  v3.0.1  |  NovaTrek Platform Engineering

Central orchestration service for NovaTrek trip scheduling. Coordinates guide

Swagger UI Download OpenAPI Spec

Integration Context

⤢svc-scheduling-orchestrator C4 context diagram

Data Store

Overview

Property Detail
Engine PostgreSQL 15 + Valkey 8
Schema scheduling
Tables schedule_requests, daily_schedules, schedule_conflicts, optimization_runs
Estimated Volume ~500 schedule requests/day
Connection Pool min 5 / max 20 / idle timeout 10min
Backup Strategy Continuous WAL archiving, daily base backup, 14-day PITR

Key Features

  • Optimistic locking per ADR-011
  • Valkey for schedule lock cache and optimization queue
  • JSONB columns for constraint parameters

Table Reference

schedule_requests

Incoming requests to create or modify daily schedules

Column Type Constraints
request_id UUID PK
schedule_date DATE NOT NULL
requested_by VARCHAR(100) NOT NULL
status VARCHAR(20) NOT NULL
constraints JSONB NOT NULL, DEFAULT '{}'
created_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_sched_req_date on schedule_date
  • idx_sched_req_status on status

daily_schedules

Published daily schedules with optimistic locking

Column Type Constraints
schedule_id UUID PK
schedule_date DATE NOT NULL, UNIQUE
assignments JSONB NOT NULL
_rev INTEGER NOT NULL, DEFAULT 1
published_at TIMESTAMPTZ NULL
created_at TIMESTAMPTZ NOT NULL
updated_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_daily_sched_date on schedule_date (UNIQUE)

schedule_conflicts

Detected conflicts during schedule optimization

Column Type Constraints
conflict_id UUID PK
schedule_id UUID NOT NULL, FK -> daily_schedules
conflict_type VARCHAR(30) NOT NULL
details JSONB NOT NULL
resolved BOOLEAN NOT NULL, DEFAULT FALSE
detected_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_conflict_schedule on schedule_id

optimization_runs

Execution history of schedule optimization algorithms

Column Type Constraints
run_id UUID PK
schedule_date DATE NOT NULL
algorithm VARCHAR(30) NOT NULL
duration_ms INTEGER NOT NULL
score DECIMAL(5,2) NULL
status VARCHAR(20) NOT NULL
started_at TIMESTAMPTZ NOT NULL
completed_at TIMESTAMPTZ NULL

Indexes:

  • idx_opt_run_date on schedule_date

Solutions Affecting This Service

Ticket Solution Capabilities Date
NTK-10003 Support Unregistered Guest Self-Service Check-In CAP-2.1, CAP-1.1, CAP-1.3 2025-02-12
NTK-10004 Guide Schedule Overwrite Bug in Scheduling Orchestrator CAP-2.2 2025-02-05

Endpoints (5 total)

POST /schedule-requests -- Request optimal schedule for a trip

Submits a scheduling request that evaluates preferred dates against

View in Swagger UI

⤢POST /schedule-requests sequence diagram

GET /schedule-requests/{request_id} -- Get schedule request status and result

Poll this endpoint to retrieve the status and, once complete, the

View in Swagger UI

⤢GET /schedule-requests/{request_id} sequence diagram

GET /schedule-optimization -- Run synchronous schedule optimization

Performs a real-time scheduling optimization for a specific trip and

View in Swagger UI

⤢GET /schedule-optimization sequence diagram

GET /schedule-conflicts -- List scheduling conflicts

Returns active scheduling conflicts for a given date and/or region.

View in Swagger UI

⤢GET /schedule-conflicts sequence diagram

POST /schedule-conflicts/resolve -- Resolve a scheduling conflict

Applies a resolution to an identified scheduling conflict. The resolution

View in Swagger UI

⤢POST /schedule-conflicts/resolve sequence diagram

Consuming Applications

Application Screens Using This Service
Operations Dashboard Daily Schedule Board, Guide Assignment
Adventure App Live Trip Map

Events Published

Event Channel Trigger Consumers
schedule.published novatrek.operations.schedule.published POST /schedule-requests svc-guide-management, svc-notifications

Events Consumed

Event Producer Channel
reservation.created svc-reservations novatrek.booking.reservation.created
emergency.triggered svc-emergency-response novatrek.safety.emergency.triggered
wildlife_alert.issued svc-wildlife-tracking novatrek.safety.wildlife-alert.issued