docs(01): add phase 1 context — project structure and UI shell decisions

.planning/phases/01-foundation/01-CONTEXT.md

@@ -0,0 +1,107 @@
+# Phase 1: Foundation - Context
+
+**Gathered:** 2026-04-05
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+The project skeleton exists — Python package structure, Pydantic data models, FastAPI API shell, device registry (CRUD + persistence), JSON show store, and a working terminal-aesthetic web UI shell with all final DAW panels laid out (most as labeled placeholders). No audio playback, no timeline logic, no UDP — those are later phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Project structure
+- **D-01:** Flat package layout — `lightsync/` directory at project root (not `src/` layout)
+- **D-02:** Package structure: `lightsync/__init__.py`, `lightsync/main.py` (entry point), `lightsync/api/`, `lightsync/devices/`, `lightsync/models/`, `lightsync/frontend/`
+- **D-03:** Frontend (HTML/CSS/JS) lives inside `lightsync/frontend/` — served via FastAPI `StaticFiles`, no separate frontend directory
+- **D-04:** Start command: `python -m lightsync` — standard module invocation, cross-platform, no install step required
+- **D-05:** `pyproject.toml` at root for dependency management
+
+### UI shell layout — Phase 1 delivers the full DAW skeleton
+- **D-06:** Full DAW skeleton from Phase 1 — all final panels exist, most as dark labeled placeholders. The layout the user will use forever is established now.
+- **D-07:** Header: ASCII art / stylized `LIGHTSYNC` title + system status indicator (API connected / offline) + current show name
+- **D-08:** Left sidebar: DEVICES panel (list of registered devices, add device form) stacked above ANIMATIONS panel (placeholder label "Phase 3+")
+- **D-09:** Main center area: large TIMELINE placeholder panel labeled `[ TIMELINE — Phase 2+ ]`
+- **D-10:** Bottom bar: TRANSPORT placeholder `[ TRANSPORT — Phase 2+ ]` spanning full width
+- **D-11:** Color accent: cyan/teal (`#00ffff` or close variant) on a dark background — terminal/hacker aesthetic, NOT generic SaaS
+
+### Visual aesthetic
+- **D-12:** Dark background (near-black, e.g. `#0a0a0a` or `#111`), monospace font (JetBrains Mono, Fira Code, or system monospace fallback)
+- **D-13:** Panel borders using CSS `border: 1px solid` with dimmed cyan/teal — like terminal window panes
+- **D-14:** Text labels in uppercase for panel headers (`DEVICES`, `ANIMATIONS`, `TIMELINE`) — terminal convention
+- **D-15:** No drop shadows, gradients, or rounded corners — flat, sharp edges throughout
+
+### Claude's Discretion
+- Exact Pydantic model field names and nesting for show files and devices (follow research/STACK.md conventions)
+- Device registry storage format (separate `devices.json` vs embedded snapshot — choose what's cleanest for the data model)
+- REST API route naming conventions
+- WebSocket message format stub (just needs to exist, Phase 2 defines the real protocol)
+- Exact CSS grid/flexbox layout implementation
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The user has built Textual TUIs before — they know what a good terminal aesthetic looks like and want the web version to match that feel: functional, keyboard-first, no visual noise
+- "Hacker style but cleaner" — the web version should look better than a terminal, not worse. Crisp borders, consistent spacing, not just raw `<pre>` text
+- The full DAW skeleton choice means: when the user opens Phase 1, they should immediately see *where* everything will live. Each placeholder panel should be clearly labeled and dimensioned correctly for what will eventually fill it
+
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Project requirements and scope
+- `.planning/PROJECT.md` — Core value, constraints, tech decisions (Python non-negotiable, Windows 11 runtime)
+- `.planning/REQUIREMENTS.md` — INF-01, INF-02, DEV-01–03, SHW-01–02, UI-01, UI-02 (this phase's requirements with acceptance criteria)
+
+### Architecture and stack
+- `.planning/ROADMAP.md` §Phase 1 — Plans list (01-01, 01-02, 01-03), success criteria, dependencies
+- `.planning/research/STACK.md` — Recommended Python stack (FastAPI version, Pydantic version, dependency list)
+- `.planning/research/ARCHITECTURE.md` — Component boundaries, show file JSON schema, data flow patterns
+
+### UI and visual design
+- `.planning/research/FEATURES.md` — Feature dependency graph (what Phase 1 must unblock for later phases)
+
+No external specs or ADRs beyond the above — all requirements are captured in decisions and planning documents.
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- None — greenfield project, no existing code
+
+### Established Patterns
+- None yet — this phase establishes the patterns all future phases follow
+
+### Integration Points
+- `lightsync/api/` → WebSocket hub (Phase 2 connects here for audio position broadcast)
+- `lightsync/devices/` → BaseDevice ABC (Phase 3 adds UDP sender, uses same abstraction)
+- `lightsync/models/` → Show and Device Pydantic models (all phases read/write these)
+- `lightsync/frontend/` → HTML/JS shell (later phases add panels into the existing layout)
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+- Show file JSON schema field decisions — not discussed (Claude's discretion per ARCHITECTURE.md guidance)
+- Device storage format (separate vs embedded) — not discussed (Claude's discretion)
+- Audio transport panel content — Phase 2
+- Animation library panel content — Phase 3
+- Timeline canvas implementation — Phase 4
+
+</deferred>
+
+---
+
+*Phase: 01-foundation*
+*Context gathered: 2026-04-05*