NTK-10006 — NTK-10006 Solution Design — Real-Time Adventure Tracking and Emergency Alerting System¶

Affected Capabilities¶

Affected Services¶

• svc-adventure-tracking
• svc-emergency-response
• svc-check-in
• svc-notifications
• svc-safety-compliance

Architecture Decisions¶

• ADR-014

Solution Contents¶

• Requirements
• Analysis
• Decisions
• Impact Assessments (5)
• User Stories
• Implementation Guidance
• Risk Assessment
• Capability Mapping

Related Solutions¶

Solutions that share services or capabilities with this design:

1. Problem Statement¶

NovaTrek Adventures lacks real-time visibility into guest locations during active adventures. Safety officers depend on manual radio check-ins and phone calls to locate guests — a process that is unreliable in backcountry areas with limited cell coverage. When emergencies occur, response is delayed by the time required to determine the guest's location.

The ticket requests a GPS tracking system that monitors all active guests in near-real-time, automatically detects emergency conditions (SOS signals, geofence violations, loss of signal), and triggers the existing emergency response workflow with precise location data.

2. Prior Art¶

3. Proposed Solution¶

3.1 Architecture Overview¶

The solution introduces one new service (svc-adventure-tracking) and integrates it with four existing services. svc-emergency-response already has a complete API spec — no new service is needed for emergency coordination.

Guest Wristband (GPS) --> svc-adventure-tracking --> svc-emergency-response
                               |                          |
                               |                          +--> svc-notifications (SMS/push/email)
                               |                          +--> svc-safety-compliance (incident log)
                               |
                               +--> Kafka: tracking.location.updated
                               +--> Kafka: tracking.anomaly.detected
                               +--> Kafka: tracking.session.started
                               +--> Kafka: tracking.session.ended

3.2 Service Responsibilities¶

3.3 Tracking Session Lifecycle¶

1. Start — checkin.completed event published by svc-check-in includes wristband_nfc_id and reservation_id. svc-adventure-tracking consumes this event and creates a tracking session.
2. Active — GPS coordinates arrive from wristband hardware at a configurable interval (default: 30 seconds). svc-adventure-tracking stores each location update and publishes tracking.location.updated events for the ops dashboard.
3. Anomaly — If the guest exits a geofence boundary, stops transmitting for longer than the configurable timeout (default: 5 minutes), or presses the SOS button, svc-adventure-tracking publishes tracking.anomaly.detected and calls POST /emergencies on svc-emergency-response.
4. End — When the adventure concludes (scheduled end time or manual check-out), svc-adventure-tracking closes the tracking session and publishes tracking.session.ended. Location history is retained for insurance compliance.

3.4 New Service: svc-adventure-tracking¶

Domain: Safety Team: Safety and Compliance Team Database: PostgreSQL 15, schema tracking

Core Endpoints (to be defined in OpenAPI spec):

Data Model:

Volume Estimates: - Active sessions: up to 500 concurrent (peak season) - Location updates: ~1,000/minute at peak (500 guests x 2 updates/min) - Location history retention: 1 year rolling, then archived to cold storage - Audit retention: 7 years (regulatory)

3.5 Event Design¶

New events published by svc-adventure-tracking:

Existing event consumed by svc-adventure-tracking:

3.6 Integration Points¶

3.7 Safety-First Design Principles¶

Per ADR-005 (Pattern 3 Default Fallback), the tracking system applies safety-first defaults:

3.8 Backward Compatibility¶

4. Quality Attributes (ISO 25010)¶

5. Decisions¶

See 3.solution/d.decisions/decisions.md for full MADR-format ADR.

6. Risks¶

See 3.solution/r.risks/risks.md for detailed risk register.

7. Impacts¶

See impact assessments in 3.solution/i.impacts/:

8. User Stories¶

See 3.solution/u.user.stories/user-stories.md for full user story set.