Web App — The Studio Dashboard

app/ is the web interface for Alchemy: FastAPI + Jinja2 + HTMX + Tailwind CSS, served by Uvicorn on port 8080.

Layout

app/
  main.py         App bootstrap, router registration, lifespan, WebSocket
  context.py      Shared context builders
  navigation.py   Workspace registry (functions, not roles)
  routes/         Page + partial routes (dashboard, assets, versions, ...)
  tools/          Larger in-app tools:
    cookbook/         Recipe editor and IDE
    image_editor/     In-browser image editing (SAM object lift, layers)
    pipeline_viewer/  Visual pipeline network diagram
    script/           Screenplay reader, timeline, breakdown tools
  templates/      Jinja2 shell + HTMX-swappable partials/
  static/         css, js, icons

The HTMX pattern

Routes detect the HX-Request header and return partials instead of full pages. This is the web equivalent of PySide signals/slots: user action (signal) → route handler (slot) → HTMX swaps a partial (widget update).

State management

• SelectionManager (POM) holds the active PathObject as a server-side singleton. All routes sync to it before building context.
• Multi-project reads go through the request context (/c/{cid} + contextvar); reads never write alchemy.json.
• The Deadline render manager lives on app.state.render_manager and pushes to clients over WebSocket.

Timeline = source of truth

The previs NLE is a staging editor, not a finishing editor. Its state lives in scene_*_timeline.json, kept 1:1 with the on-screen view and exportable as OTIO. Finals go to Resolve/Premiere.

Verifying changes

Use FastAPI's TestClient with the venv python for route-level checks, or run a preview instance on port 8091+ (see Getting Started).