svc-adventure-tracking¶
NovaTrek Adventure Tracking Service | Operations | v1.0.0 | NovaTrek Operations Team
Manages real-time GPS tracking of guests on active adventures. Receives position
Swagger UI Download OpenAPI Spec CI/CD Pipeline Source Code Technology Stack
Integration Context¶
Data Store¶
Entity Relationship Diagram¶
Overview¶
| Property | Detail |
|---|---|
| Engine | PostgreSQL 15 + PostGIS |
| Schema | tracking |
| Tables | tracking_sessions, positions, geofences |
| Estimated Volume | ~50,000 positions/day (peak season), ~500 sessions/day |
| Connection Pool | min 10 / max 50 / idle timeout 5min |
| Backup Strategy | Daily pg_dump, 90-day retention for positions, indefinite for sessions |
Key Features¶
- PostGIS spatial indexing for geofence containment queries
- Hypertable-style time partitioning on positions (monthly)
- Automatic session lifecycle management (ACTIVE -> COMPLETED on checkout)
- Pattern-based GPS frequency (Pattern 1=60s, Pattern 2=30s, Pattern 3=10s)
- 90-day retention policy for position data
- SSE live-stream for real-time dashboard updates
Table Reference¶
tracking_sessions¶
Active and historical adventure tracking sessions linked to check-ins
| Column | Type | Constraints |
|---|---|---|
session_id | UUID | PK, DEFAULT gen_random_uuid() |
checkin_id | UUID | NOT NULL, FK -> svc-check-in |
guest_id | UUID | NOT NULL |
adventure_id | UUID | NOT NULL |
guide_id | UUID | NULL |
device_id | VARCHAR(100) | NOT NULL |
status | VARCHAR(20) | NOT NULL, CHECK (ACTIVE, PAUSED, COMPLETED, EMERGENCY) |
gps_frequency_seconds | INTEGER | NOT NULL, DEFAULT 10 |
started_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
completed_at | TIMESTAMPTZ | NULL |
created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
idx_session_statusonstatus(BTREE)idx_session_guestonguest_id(BTREE)idx_session_checkinoncheckin_id(UNIQUE)
positions¶
GPS position reports from guest devices with SOS and battery metadata
| Column | Type | Constraints |
|---|---|---|
position_id | UUID | PK, DEFAULT gen_random_uuid() |
session_id | UUID | NOT NULL, FK -> tracking_sessions |
location | GEOMETRY(Point, 4326) | NOT NULL |
altitude_meters | NUMERIC(7,2) | NULL |
accuracy_meters | NUMERIC(6,2) | NOT NULL |
speed_kmh | NUMERIC(5,2) | NULL |
heading_degrees | NUMERIC(5,2) | NULL |
battery_percent | SMALLINT | NULL |
sos_flag | BOOLEAN | NOT NULL, DEFAULT FALSE |
recorded_at | TIMESTAMPTZ | NOT NULL |
received_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
idx_position_session_timeonsession_id, recorded_at DESC(BTREE)idx_position_locationonlocation(GIST)idx_position_sosonsos_flag(BTREE)
geofences¶
Geographic boundaries for adventure trails and restricted zones
| Column | Type | Constraints |
|---|---|---|
geofence_id | UUID | PK, DEFAULT gen_random_uuid() |
adventure_id | UUID | NOT NULL |
name | VARCHAR(200) | NOT NULL |
geofence_type | VARCHAR(30) | NOT NULL, CHECK (TRAIL_BOUNDARY, RESTRICTED_ZONE, CHECKPOINT, HAZARD_ZONE) |
boundary | GEOMETRY(Polygon, 4326) | NOT NULL |
alert_on_exit | BOOLEAN | NOT NULL, DEFAULT TRUE |
active | BOOLEAN | NOT NULL, DEFAULT TRUE |
created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
idx_geofence_adventureonadventure_id(BTREE)idx_geofence_boundaryonboundary(GIST)
Solutions Affecting This Service¶
| Ticket | Solution | Capabilities | Date |
|---|---|---|---|
| NTK-10006 | Real-Time Adventure Tracking and Emergency Alerting System | CAP-2.1, CAP-3.2, CAP-3.3, CAP-7.2 | 2026-03-14 |
Endpoints (10 total)¶
GET /tracking-sessions -- List active tracking sessions¶
Returns all currently active tracking sessions. Supports filtering by
POST /tracking-sessions -- Create a tracking session¶
Creates a new tracking session for a guest. Typically triggered by consuming
GET /tracking-sessions/{session_id} -- Get tracking session details¶
Returns a tracking session including the most recent position, session
PATCH /tracking-sessions/{session_id} -- Update tracking session status¶
Updates a tracking session. Used to terminate sessions (adventure complete
GET /tracking-sessions/{session_id}/positions -- Get position history for a tracking session¶
Returns the position history for a tracking session. Supports time range
POST /positions -- Report a GPS position update¶
Receives a GPS position update from a wristband device. The position is
POST /positions/batch -- Report a batch of GPS position updates¶
Receives a batch of GPS position updates. Used when wristbands buffer
GET /geofences -- List geofences¶
Returns geofences configured for adventures. Each geofence defines a
POST /geofences -- Create a geofence¶
Defines a new geofence boundary. Geofences are evaluated against
GET /live-stream -- Subscribe to live position updates (SSE)¶
Server-Sent Events stream of real-time position updates for all active