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