Skip to content

svc-trail-management

NovaTrek Trail Management Service  |  Product Catalog  |  v1.1.0  |  NovaTrek Platform Team

Manages trail definitions, waypoints, difficulty ratings, closures, and real-time

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

Delivery Status

Delivery Wave: 1 -- Guest Identity and Product Catalog

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-trail-management C4 context diagram

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

Data Store

Entity Relationship Diagram

⤢svc-trail-management entity relationship diagram

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

Overview

Property Detail
Engine PostGIS (PostgreSQL 15)
Schema trails
Tables trails, waypoints, closures, condition_reports
Estimated Volume ~200 condition updates/day, ~5K trail reads/day
Connection Pool min 5 / max 15 / idle timeout 10min
Backup Strategy Daily pg_dump with PostGIS extensions, 14-day retention

Key Features

  • PostGIS geometry columns for trail routes and waypoints
  • Spatial indexes (GiST) for proximity queries
  • Time-series condition data with hypertable extension

Table Reference

trails

Trail definitions with geospatial route geometry

Column Type Constraints
trail_id UUID PK
name VARCHAR(200) NOT NULL
difficulty VARCHAR(20) NOT NULL
length_km DECIMAL(6,2) NOT NULL
elevation_gain_m INTEGER NULL
route GEOMETRY(LineString, 4326) NOT NULL
status VARCHAR(20) NOT NULL, DEFAULT 'open'
region_id UUID NOT NULL
updated_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_trail_route on route (GiST spatial)
  • idx_trail_status on status
  • idx_trail_region on region_id

waypoints

Points of interest and navigation markers along trails

Column Type Constraints
waypoint_id UUID PK
trail_id UUID NOT NULL, FK -> trails
name VARCHAR(100) NOT NULL
location GEOMETRY(Point, 4326) NOT NULL
waypoint_type VARCHAR(30) NOT NULL
elevation_m INTEGER NULL
sequence_order INTEGER NOT NULL

Indexes:

  • idx_wp_trail on trail_id, sequence_order
  • idx_wp_location on location (GiST spatial)

condition_reports

Time-series trail condition observations from guides and sensors

Column Type Constraints
report_id UUID PK
trail_id UUID NOT NULL, FK -> trails
condition VARCHAR(30) NOT NULL
details TEXT NULL
reported_by VARCHAR(100) NOT NULL
reported_at TIMESTAMPTZ NOT NULL

Indexes:

  • idx_cond_trail_time on trail_id, reported_at DESC

Solutions Affecting This Service

Ticket Solution Capabilities Date
NTK-10001 Add Elevation Profile Data to Trail Response CAP-2.4 2025-02-01

Endpoints (9 total)

GET /trails -- Search trails

Search and filter trails by region, difficulty, activity type, and status.

View in Swagger UI

⤢GET /trails sequence diagram

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

POST /trails -- Create a new trail

Registers a new trail in the system. Requires operations or admin role.

View in Swagger UI

⤢POST /trails sequence diagram

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

GET /trails/{trail_id} -- Get trail details

Returns complete trail information including metadata, geography, and current status.

View in Swagger UI

⤢GET /trails/{trail_id} sequence diagram

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

PATCH /trails/{trail_id} -- Update trail details

Partially updates trail metadata. Does not modify waypoints or closures.

View in Swagger UI

⤢PATCH /trails/{trail_id} sequence diagram

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

GET /trails/{trail_id}/waypoints -- List waypoints for a trail

Returns all waypoints along the trail in sequence order.

View in Swagger UI

⤢GET /trails/{trail_id}/waypoints sequence diagram

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

POST /trails/{trail_id}/waypoints -- Add a waypoint to a trail

Appends a new waypoint to the trail. Position in sequence can be specified.

View in Swagger UI

⤢POST /trails/{trail_id}/waypoints sequence diagram

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

GET /trails/{trail_id}/closures -- List closures for a trail

Returns all current and scheduled closures for the specified trail.

View in Swagger UI

⤢GET /trails/{trail_id}/closures sequence diagram

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

POST /trails/{trail_id}/closures -- Create a trail closure

Records a closure for the trail. Automatically updates trail status to

View in Swagger UI

⤢POST /trails/{trail_id}/closures sequence diagram

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

GET /trails/{trail_id}/conditions -- Get current trail conditions

Returns the latest condition assessment for the trail, combining data from

View in Swagger UI

⤢GET /trails/{trail_id}/conditions sequence diagram

✎ Architect-authored — overrides auto-generated baseline Source: architecture/diagrams/endpoints/svc-trail-management--get-trails-trail_id-conditions.puml

Consuming Applications

Application Screens Using This Service
Guest Portal Trip Browser
Operations Dashboard Daily Schedule Board, Guide Assignment
Adventure App Live Trip Map, Weather and Trail Alerts

Events Consumed

Event Producer Channel
wildlife_alert.issued svc-wildlife-tracking novatrek.safety.wildlife-alert.issued