NTK-10002 — NTK-10002: Adventure Category Classification - Solution Design¶

Affected Capabilities¶

Affected Services¶

• svc-check-in
• svc-adventure-catalog

Architecture Decisions¶

• ADR-004
• ADR-005

Solution Contents¶

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

Related Solutions¶

Solutions that share services or capabilities with this design:

1. Problem Statement¶

NovaTrek's check-in service (svc-check-in) currently determines the guest check-in UI experience using the activity_type field from the trip reservation. There are 10 activity types, but they are too coarse to accurately classify the check-in requirements. This results in two failure modes:

1. Over-servicing: Guests on simple activities (day hikes, bouldering) are presented with unnecessary gear pickup and guide meetup screens, adding friction and confusion.
2. Under-servicing: Guests on complex activities (backcountry camping, technical canyoneering) receive an insufficient check-in flow that skips critical safety steps like medical clearance and transport coordination.

Guest satisfaction scores for the check-in experience have declined for 3 consecutive quarters. Operational staff report that manual interventions are required in approximately 15% of check-ins to correct the flow.

2. Solution Overview¶

Introduce an adventure category classification system that replaces the coarse activity_type-based check-in determination with a granular, 25-category classification mapped to 3 distinct check-in UI patterns. The classification is configuration-driven, cached in memory, and supports booking source overrides.

Key Design Principles¶

• Configuration over code: The category-to-pattern mapping is defined in YAML configuration, not hardcoded.
• Safety-first defaults: Unknown or unmapped categories default to Pattern 3 (Full Service).
• Override precedence: Booking source overrides are evaluated before category classification.
• Backward compatible: The existing activity_type field is retained; adventure_category is additive.

3. Classification Table¶

4. Booking Source Override Rules¶

Override evaluation occurs BEFORE category classification. If a booking source has an override, the category lookup is skipped entirely.

5. Pattern Definitions¶

Pattern 1 - Basic¶

• Single confirmation screen
• Guest confirms name, reservation ID, and trip date
• Estimated kiosk time: 30 seconds
• No gear pickup, no guide meetup, no additional steps

Pattern 2 - Gear Required¶

• Screen 1: Confirmation (same as Pattern 1)
• Screen 2: Gear pickup checklist with barcode scanning for each item
• Screen 3: Safety briefing acknowledgment with digital signature
• Estimated kiosk time: 3-5 minutes

Pattern 3 - Full Service¶

• Screen 1: Confirmation (same as Pattern 1)
• Screen 2: Gear pickup checklist with barcode scanning
• Screen 3: Guide introduction with guide photo, name, and contact info
• Screen 4: Transport coordination with departure time, pickup location map
• Screen 5: Medical clearance form (pre-filled from reservation if available)
• Screen 6: Final summary with all check-in details and emergency contact info
• Estimated kiosk time: 8-12 minutes

6. Impacted Components¶

7. Architecture Decision: Configuration-Driven Classification¶

Context: The category-to-pattern mapping needs to be maintainable and performant. Options considered were database-driven (with admin UI) and configuration-driven (YAML in Spring Cloud Config).

Decision: Use configuration-driven classification with Spring Cloud Config.

Rationale: - The mapping is relatively stable (changes expected less than once per sprint) - YAML config files are version-controlled and reviewable through standard PR processes - No new database table, migration, or admin UI required - In-memory cache provides sub-millisecond lookup performance - Spring Cloud Config /actuator/refresh endpoint enables on-demand reload

Cache Strategy: The classification config is loaded into a ConcurrentHashMap at service startup. It is refreshed on Spring Cloud Config refresh events or when the configurable TTL (default: 5 minutes) expires. The @Cacheable annotation on the ClassificationService.getPattern() method handles this transparently.

8. Data Flow¶

1. Guest initiates check-in at kiosk or mobile device.
2. svc-check-in receives the check-in request with reservation_id.
3. svc-check-in retrieves reservation details from svc-reservations, which includes booking_source and adventure_category.
4. ClassificationService evaluates booking source override rules first.
5. If an override applies, the override pattern is returned immediately.
6. If no override applies, ClassificationService looks up the adventure_category in the cached classification table.
7. If the category is found, the mapped pattern is returned.
8. If the category is null, empty, or not found, Pattern 3 (Full Service) is returned as the default.
9. svc-check-in renders the check-in UI flow corresponding to the determined pattern.
10. The POST /check-ins response includes the determined_pattern field.

9. Deployment Notes¶

• Phased rollout: Deploy classification config first, then enable the feature via feature flag (novatrek.checkin.use-category-classification=true).
• Backward compatible: When the feature flag is disabled, the existing activity_type-based logic remains active.
• Rollback: Disable the feature flag to revert to previous behavior instantly. No data migration required.
• Monitoring: Add metrics for pattern distribution (checkin.pattern.determined counter with pattern tag) to verify classification accuracy post-deployment.

10. Testing Strategy¶

• Unit tests: Test ClassificationService with all 25 categories to verify correct pattern mapping.
• Unit tests: Test booking source override logic for PARTNER_API and WALK_IN.
• Unit tests: Test fallback behavior for null, empty, and unrecognized categories.
• Integration tests: End-to-end check-in flow for each pattern, verifying correct screens are rendered.
• Integration tests: Verify that config refresh updates the classification mapping without restart.
• Performance tests: Validate that classification lookup adds less than 1ms to check-in request latency.

11. Source Code Analysis¶

Analysis of the current AdventureCategoryClassifier.java reveals several critical gaps that this solution addresses:

Current Code Issues¶

CRITICAL Safety Concern¶

The current default to Pattern 1 for unknown categories means that a guest booked for an unrecognized high-risk activity (such as a newly added ICE_CLIMBING category not yet in the classifier) would receive only a confirmation screen -- bypassing gear verification, safety briefing, guide meetup, and medical clearance. This is the primary motivator for ADR-NTK10002-002 mandating Pattern 3 as the fallback.

Data Model Readiness¶

The CheckInRecord.java entity already has adventureCategory (line 40) and uiPattern (line 43) fields, confirming partial readiness for the classification feature. The remaining work is replacing the hardcoded classifier with the config-driven ClassificationService.

12. Service Interaction Changes¶

Current Service Interactions¶

Guest -> svc-check-in: POST /check-ins (reservation_id)
svc-check-in -> svc-reservations: GET reservation (to read activity_type)
svc-check-in: Hardcoded two-tier classification by activity_type
svc-check-in -> Guest: Check-in response (no pattern info)

Proposed Service Interactions¶

Guest -> svc-check-in: POST /check-ins (reservation_id)
svc-check-in -> svc-reservations: GET reservation (to read booking_source + adventure_category)
svc-check-in -> ClassificationService: determinePattern(bookingSource, adventureCategory)
ClassificationService -> Spring Cloud Config: Load classification mapping (cached, TTL 5 min)
svc-check-in -> Guest: Check-in response (includes determined_pattern, pattern_name)

No new service-to-service network calls are introduced. The ClassificationService is an internal component within svc-check-in. The svc-reservations call already exists; the only change is reading adventure_category in addition to activity_type.

svc-trip-catalog Data Model Addition¶

The Trip schema in svc-trip-catalog must be extended with an adventure_category field (string enum, nullable). This field is populated when trips are created or updated and flows through svc-reservations to svc-check-in at check-in time.

13. Version History¶