# Architecture

Browser (React, inherited Gen Space and timeline)
→ Node web service (session authentication, file I/O, streaming HTTP forwarding)
→ Athena Deck shared API port in Video mode
→ original LTX Desktop backend.

The backend address may alternatively point directly to the native LTX API.
The web service forwards `/ltx/api/...` to `/api/...`, preserving method, body,
query, response status and body. No model-specific request translation. A fixed,
operator-configured upstream prevents browser-controlled proxy targets. Tokens
are loaded from files at startup and never sent to the browser. Native streaming
HTTP responses and polling are supported; WebSocket forwarding is not implemented.

`frontend/lib/web-platform.ts` implements the inherited typed `electronAPI` boundary
in the browser. It is an OS/file integration replacement, not a model API adapter.
The application shell no longer calls Python installers, model setup, first-run
license acceptance, Electron updates or backend process start/stop. Unsupported
functions throw explicit errors; timeline rendering is visibly disabled.

Media: browsers cannot send server paths without first uploading. File dialogs
upload immediately; drag-and-drop uses temporary blob URLs until a generation or
asset import resolves the file. Server stores UUID filenames in a shared input
folder; its backend-visible path is returned. The web service and LTX must see the
SAME files (Docker bind mounts can expose different absolute paths). Existing LTX
outputs are mounted read-only. Only configured input/output roots are readable;
traversal and symlinks escaping those roots are rejected. ffmpeg/ffprobe create
thumbnails, dimensions and extracted frames on CPU; they are not inference runtimes.
Network protocols are disabled for media inspection. HTTP Range supports seeking.
Uploads, copied assets and thumbnails are mode 0640. Provision the writable input
folder with a shared backend group and mode 2750 (setgid), so new files inherit
that group. Both service identities must be able to traverse/read the shared
folder; a root UID with dropped capabilities cannot bypass ordinary permissions.

Projects: initial preview retains the upstream browser-local project storage.
Projects are specific to this browser/origin, not multiuser or cross-device synced.
JSON backup and restore are provided. Media is persistent in the mounted input directory.
Deleting a project removes its index/metadata, not shared LTX files.

Security: single shared login, >=16-character operator-provided password, in-memory
12-hour sessions, HttpOnly SameSite=Strict cookie, Secure for configured HTTPS,
login throttling, same-origin requests, fixed upstream, no Docker socket or GPU
access. PUBLIC_ORIGIN must match the user's actual browser address. For remote
access use HTTPS or an SSH tunnel; no unencrypted public password login.
The existing native LTX API has operator-level functionality; authenticated web
users are trusted operators, not isolated tenants. The input directory must be
writable only by trusted service accounts. This is a preview, not a public SaaS.

## Current limitations

- No native timeline video rendering; FCPXML exports metadata only and references
  backend media paths. A portable XML/media package needs a later export stage.
- No server-side project library, cross-browser synchronization or multiuser roles.
- No desktop Hugging Face OAuth, server-folder chooser or Electron updater.
- Exact feature support depends on the selected LTX backend/model. Browser porting
  does not add Retake/Extend support to a model that lacks it.
- Another container stack needs access to the same media storage; an API URL alone
  does not transport backend filesystem files. No SSH/SCP credentials are embedded.
- First release validated with a synthetic backend, not a real GPU generation.