108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
# 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*
|