---
phase: 03-visual-flattening
plan: 01
subsystem: ui
tags: [uitableview, flattening, sortorder, swift]

# Dependency graph
requires:
  - phase: 01-semantic-position-model
    provides: SortOrderProvider for game time → sortOrder conversion
  - phase: 02-constraint-validation
    provides: ItineraryConstraints for drag validation
provides:
  - ItineraryFlattener pure utility for deterministic display ordering
  - Refactored reloadData() using sortOrder-based flattening
affects: [03-02-flattening-tests, 04-drag-drop]

# Tech tracking
tech-stack:
  added: []
  patterns: [pure-function-for-flattening, sortorder-based-display-ordering]

key-files:
  created:
    - SportsTime/Core/Models/Domain/ItineraryFlattener.swift
  modified:
    - SportsTime/Features/Trip/Views/ItineraryTableViewController.swift

key-decisions:
  - "Day headers are not positioned items - always first in each day"
  - "Games get sortOrder from SortOrderProvider.initialSortOrder(forGameTime:)"
  - "Travel sortOrder looked up from itineraryItems by city name matching"
  - "Pure flatten function enables unit testing without UITableView"

patterns-established:
  - "ItineraryFlattener.flatten(): Pure function for hierarchical to flat conversion"
  - "gamesByDay dictionary: Group games by day number before flattening"

# Metrics
duration: 3min
completed: 2026-01-18
---

# Phase 3 Plan 1: Visual Flattening Summary

**Pure ItineraryFlattener utility replacing bucket-based flattening with sortOrder-based deterministic display ordering**

## Performance

- **Duration:** 3 min
- **Started:** 2026-01-18T21:52:57Z
- **Completed:** 2026-01-18T21:55:13Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments

- Created `ItineraryFlattener` enum with pure `flatten()` function
- Replaced bucket-based flattening (beforeGames/afterGames) with sortOrder sort
- Deterministic display order: same semantic state always produces same row order
- Updated architecture documentation to reflect sortOrder-based approach

## Task Commits

Each task was committed atomically:

1. **Task 1: Create ItineraryFlattener utility** - `fdfc912` (feat)
2. **Task 2: Refactor reloadData() to use ItineraryFlattener** - `dd1fd82` (refactor)

## Files Created/Modified

- `SportsTime/Core/Models/Domain/ItineraryFlattener.swift` - Pure flatten function with sortOrder-based ordering
- `SportsTime/Features/Trip/Views/ItineraryTableViewController.swift` - Refactored reloadData() to use flattener

## Decisions Made

- **Day headers not positioned:** Day headers are always first in each day, not part of the sortOrder-based ordering. This is a structural anchor.
- **Flattener is a pure function:** No instance state, no side effects. Enables easy unit testing and guarantees determinism.
- **gamesByDay dictionary:** Built in reloadData() to pass to flattener rather than having flattener access day.games directly.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- ItineraryFlattener ready for unit tests in plan 03-02
- reloadData() now uses pure flattening, enabling snapshot testing
- Phase 4 drag-drop can rely on deterministic flatten output

---
*Phase: 03-visual-flattening*
*Completed: 2026-01-18*