Skip to content

svc-wildlife-tracking

NovaTrek Wildlife Tracking Service  |  Safety  |  v1.0.0  |  NovaTrek Safety and Compliance Team

Monitors wildlife activity near NovaTrek adventure trails, processes

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

Delivery Status

Delivery Wave: 6 -- External Integrations

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-wildlife-tracking C4 context diagram

⚙ Generated from architecture/specs/svc-wildlife-tracking.yaml + cross-service-calls.yaml

Data Store

Entity Relationship Diagram

⤢svc-wildlife-tracking entity relationship diagram

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

Overview

Property Detail
Engine PostgreSQL 15
Schema wildlife
Tables sightings, wildlife_alerts, species, habitat_zones
Estimated Volume ~200 sightings/month peak season
Connection Pool min 3 / max 10 / idle timeout 10min
Backup Strategy Daily base backup, 14-day PITR

Key Features

  • PostGIS extension for geospatial queries on sighting locations
  • Indexes on species_id and trail_id for sighting lookups
  • Optimistic locking via _rev on wildlife_alerts
  • Automatic alert generation when dangerous species sighted near trails

Table Reference

sightings

Wildlife sighting reports from guides, guests, and automated sensors

Column Type Constraints
sighting_id UUID PK, DEFAULT gen_random_uuid()
species_id UUID NOT NULL, FK -> species
latitude DOUBLE PRECISION NOT NULL
longitude DOUBLE PRECISION NOT NULL
altitude_meters DOUBLE PRECISION NULL
reported_by VARCHAR(100) NOT NULL
reporter_type VARCHAR(20) NOT NULL, DEFAULT 'guide'
observation_notes TEXT NULL
animal_count INTEGER NOT NULL, DEFAULT 1
behavior VARCHAR(20) NULL
photo_url TEXT NULL
trail_id UUID NULL
alert_triggered BOOLEAN NOT NULL, DEFAULT false
reported_at TIMESTAMPTZ NOT NULL, DEFAULT NOW()

Indexes:

  • idx_sighting_species on species_id
  • idx_sighting_trail on trail_id
  • idx_sighting_date on reported_at DESC
  • idx_sighting_location on latitude, longitude (GIST (PostGIS))

wildlife_alerts

Active wildlife alerts affecting trail corridors

Column Type Constraints
alert_id UUID PK, DEFAULT gen_random_uuid()
species_id UUID NOT NULL, FK -> species
sighting_id UUID NULL, FK -> sightings
threat_level VARCHAR(10) NOT NULL
status VARCHAR(20) NOT NULL, DEFAULT 'active'
affected_trail_ids UUID[] NOT NULL
radius_meters DOUBLE PRECISION NULL
recommended_action VARCHAR(20) NULL
notes TEXT NULL
issued_at TIMESTAMPTZ NOT NULL, DEFAULT NOW()
expires_at TIMESTAMPTZ NULL
cancelled_at TIMESTAMPTZ NULL
_rev VARCHAR(36) NOT NULL

Indexes:

  • idx_walert_status on status
  • idx_walert_species on species_id
  • idx_walert_issued on issued_at DESC

species

Master species registry with threat classifications

Column Type Constraints
species_id UUID PK, DEFAULT gen_random_uuid()
common_name VARCHAR(100) NOT NULL, UNIQUE
scientific_name VARCHAR(200) NOT NULL
threat_level VARCHAR(10) NOT NULL, DEFAULT 'none'
category VARCHAR(20) NOT NULL
description TEXT NULL
safety_guidance TEXT NULL
regions TEXT[] NULL
active_seasons TEXT[] NULL

Indexes:

  • idx_species_threat on threat_level
  • idx_species_name on common_name

habitat_zones

Defined geographic zones with known wildlife populations

Column Type Constraints
zone_id UUID PK, DEFAULT gen_random_uuid()
name VARCHAR(100) NOT NULL
boundary GEOMETRY(Polygon, 4326) NOT NULL
primary_species UUID[] NULL
activity_level VARCHAR(10) NOT NULL, DEFAULT 'low'
season VARCHAR(10) NULL
overlapping_trail_ids UUID[] NULL

Indexes:

  • idx_habitat_boundary on boundary (GIST (PostGIS))
  • idx_habitat_activity on activity_level

Endpoints (10 total)

GET /sightings -- List wildlife sighting reports with filters

View in Swagger UI

⤢GET /sightings sequence diagram

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

POST /sightings -- Report a new wildlife sighting

Records a wildlife sighting from a guide or guest. If the species is

View in Swagger UI

⤢POST /sightings sequence diagram

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

GET /sightings/{sighting_id} -- Get details of a specific wildlife sighting

View in Swagger UI

⤢GET /sightings/{sighting_id} sequence diagram

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

GET /alerts -- List active wildlife alerts

View in Swagger UI

⤢GET /alerts sequence diagram

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

POST /alerts -- Issue a wildlife alert for a trail or region

Creates a new wildlife alert that may trigger trail closures,

View in Swagger UI

⤢POST /alerts sequence diagram

✎ Architect-authored — overrides auto-generated baseline Source: architecture/diagrams/endpoints/svc-wildlife-tracking--post-alerts.puml

GET /alerts/{alert_id} -- Get wildlife alert details

View in Swagger UI

⤢GET /alerts/{alert_id} sequence diagram

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

PATCH /alerts/{alert_id} -- Update alert status or details

View in Swagger UI

⤢PATCH /alerts/{alert_id} sequence diagram

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

GET /species -- List known species in the wildlife database

View in Swagger UI

⤢GET /species sequence diagram

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

GET /species/{species_id} -- Get species details and behavioral data

View in Swagger UI

⤢GET /species/{species_id} sequence diagram

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

GET /habitat-zones -- List habitat zones with activity levels

View in Swagger UI

⤢GET /habitat-zones sequence diagram

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

Consuming Applications

Application Screens Using This Service
Operations Dashboard Safety Incident Board
Adventure App Weather and Trail Alerts

Events Published

Event Channel Trigger Consumers
wildlife_alert.issued novatrek.safety.wildlife-alert.issued POST /alerts svc-notifications, svc-scheduling-orchestrator, svc-trail-management, svc-analytics