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

Integration Context¶

Data Store¶

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

POST `/trails` -- Create a new trail¶

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

View in Swagger UI

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

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

View in Swagger UI

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

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

View in Swagger UI

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

Returns all waypoints along the trail in sequence order.

View in Swagger UI

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

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

Returns all current and scheduled closures for the specified trail.

View in Swagger UI

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

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

View in Swagger UI

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

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

View in Swagger UI

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`