Skip to content

architecture.md

Latest commit

 

History

History
134 lines (87 loc) · 4.36 KB

architecture.md

File metadata and controls

134 lines (87 loc) · 4.36 KB

Lighting Lab Architecture

Purpose

Lighting Lab is a browser-based prototype for exploring how a programmable architectural lighting system could be organized around a stylized landmark tower. The architecture is intentionally split so rendering, runtime behavior, scene logic, and safety logic remain understandable and independently evolvable.

The tower in this project is fictionalized. It is not a digital twin of Tokyo Skytree or any other real-world landmark.

Architectural Layers

Presentation Layer

The presentation layer is built from React components and Tailwind-driven styling:

  • src/components/layout: top-level shell and page framing
  • src/components/sidebar: scene library, details, system state, and control surfaces
  • src/components/tower: React Three Fiber viewport, tower mesh, and fixture rendering
  • src/components/ui: shared presentation primitives such as badges

This layer is responsible for interaction, layout, typography, and visual polish. It does not own domain behavior.

Runtime Coordination Layer

The runtime coordinator lives primarily in src/hooks/useLightingSystem.ts.

It resolves:

  • current operating mode
  • scheduled scene selection
  • manual scene holds
  • override activation and expiration
  • safety snapshot aggregation
  • UI-facing runtime state

This layer is the bridge between pure domain logic and the rendered interface.

Scene Engine Layer

The scene engine remains data-driven and pure:

The engine computes lighting state over time without knowing anything about React components or UI layout.

Scheduling Layer

Scheduling logic lives in src/lib/scheduler/index.ts, with schedule data in src/data/schedule.ts.

This layer resolves:

  • the current scheduled scene
  • the next scheduled scene
  • minutes until the next handoff
  • runtime mode precedence
  • override activation and reversion

Constraints Layer

Safety and validation logic live in src/lib/constraints/index.ts.

This layer is responsible for:

  • scene validation
  • fallback scene selection
  • brightness capping
  • frame smoothing
  • safety issue reporting

The goal is to keep safety behavior explicit, observable, and separate from scene authorship.

Rendering Flow

At a high level, the runtime works like this:

  1. The scheduler resolves the current scheduled scene.
  2. Mode logic decides whether scheduled, manual, or override playback should win.
  3. The constraint layer validates the requested scene and may substitute a fallback.
  4. The scene engine computes per-fixture emissive color and intensity.
  5. Constraint logic caps and smooths the frame.
  6. FixtureLayer applies the final values to the existing fixture materials.

This keeps the visual layer thin while the runtime stays testable and predictable.

Source Layout

src/data

Static runtime data:

  • scenes.ts
  • schedule.ts
  • overridePresets.ts
  • systemState.ts

src/types

Shared TypeScript contracts for scenes, tower fixtures, runtime state, schedules, overrides, and safety telemetry.

src/hooks

Runtime orchestration hooks. At the moment, useLightingSystem is the main coordinator for application state.

src/lib

Pure domain logic:

  • scene-engine
  • scheduler
  • constraints
  • outputs reserved for future downstream adapters

Design Goals

  • Keep rendering separate from logic.
  • Keep scenes declarative and data-driven.
  • Treat fixtures as individual addressable units.
  • Make runtime state legible in the UI.
  • Favor composable modules over component-level hardcoding.
  • Preserve the stylized-tower framing so the project remains clearly fictionalized.

Current Status

The current demo includes:

  • a polished public-facing control deck
  • a stylized tower with addressable fixtures
  • animated, layered scenes
  • scheduling and override behavior
  • safety-aware output handling

The main future expansion areas are richer diagnostics, output adapters, and more advanced operational tooling.