Files

Trey t 6426c0cacd docs(01): capture phase context

Phase 01: Semantic Position Model
- Implementation decisions documented
- Phase boundary established

2026-01-18 13:35:11 -06:00

2.5 KiB

Raw Blame History

Phase 1: Semantic Position Model - Context

Gathered: 2026-01-18 Status: Ready for planning

## Phase Boundary

All movable items have a persistent semantic position (day: Int, sortOrder: Double) that survives data reloads. Games are immovable anchors ordered by game time. Travel segments and custom items can be repositioned. This phase establishes the data model only — constraint validation, flattening, and drag interaction are separate phases.

## Implementation Decisions

sortOrder assignment

Use integer spacing (1, 2, 3...) for initial sortOrder values
Midpoint insertion (1.5, 1.25, etc.) when placing between items
Claude's discretion on threshold/rebalancing strategy when gaps get very small
Claude's discretion on negative vs positive sortOrder for "before games" items
Claude's discretion on Double vs Decimal storage type

Day boundaries

Day = trip day backed by calendar date (Day 1 = trip.startDate, Day 2 = startDate + 1, etc.)
Day number derived as: calendar_days_since(trip.startDate) + 1
Games belong to their start date, even if they run past midnight
Show all days including empty ones (no skipping gaps in the trip)

Travel segment identity

Each travel segment has a unique UUID (not keyed by route)
Same route (e.g., Chicago→Boston) can appear multiple times in a trip
Travel carries: from city, to city, estimated distance, estimated duration
Moving travel to different day just updates the day property (no recalculation)

Position initialization

Games get sortOrder assigned by Claude based on game time
Auto-generated travel appears after the origin city's games
Custom items added via "+" button on day headers, inserted at top of that day
Claude's discretion on handling position updates when trip is edited

Claude's Discretion

Exact sortOrder rebalancing threshold and strategy
Whether to use negative sortOrder or offset games to higher values for "before" positioning
Double vs Decimal for sortOrder storage
Initial sortOrder derivation for games (time-based or sequential)
Position preservation vs recomputation on trip edits

## Specific Ideas

Day headers should have a "+" button for adding custom items
When user taps "+", item is added to top of that day (lowest sortOrder)

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 01-semantic-position-model Context gathered: 2026-01-18

2.5 KiB Raw Blame History