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

Phase 1: Foundation - Context

Gathered: 2026-04-05 Status: Ready for planning

## 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.

## 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

## 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

<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 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

---

Phase: 01-foundation Context gathered: 2026-04-05