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 Live Service (Dev) Azure Portal CI/CD Pipeline Source Code Technology Stack

Delivery Status

Delivery Wave: 3 -- Day-of-Adventure 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-scheduling-orchestrator C4 context diagram

⚙ Generated from architecture/specs/svc-scheduling-orchestrator.yaml + cross-service-calls.yaml

Data Store

Entity Relationship Diagram

⤢svc-scheduling-orchestrator entity relationship diagram

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

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-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

✎ Architect-authored — overrides auto-generated baseline Source: architecture/diagrams/endpoints/svc-scheduling-orchestrator--post-schedule-requests.puml

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

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

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

✎ Architect-authored — overrides auto-generated baseline Source: architecture/diagrams/endpoints/svc-scheduling-orchestrator--get-schedule-optimization.puml

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

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

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

✎ Architect-authored — overrides auto-generated baseline Source: architecture/diagrams/endpoints/svc-scheduling-orchestrator--post-schedule-conflicts-resolve.puml

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