Initial Animatrix import

Animatrix Project Truth.md

@@ -0,0 +1,132 @@
+# Animatrix Project Truth
+
+Date: 2026-04-17
+
+This document is the operational truth artifact for Animatrix.
+
+This is the first pass. It is intentionally direct and incomplete-by-design rather than padded. Later passes should append deeper sections instead of replacing the existing truths.
+
+## 1. What Animatrix Is
+
+Animatrix is a production-oriented creative surface for grounded Wan 2.2 generation over the Desineuron stack.
+
+It is not a general-purpose ComfyUI editor.
+
+It is a constrained application that:
+
+- stores user assets on the Linux box
+- authenticates operators locally
+- submits generation jobs through the backend
+- targets the stable Comfy ingress at `https://comfy.desineuron.in`
+- uses local Wan model files on the GPU box NVMe through ComfyUI
+
+## 2. Current Runtime Topology
+
+Current live topology:
+
+- frontend: Linux box
+- backend: Linux box
+- auth and job DB: SQLite on Linux box
+- asset storage: Linux box local storage
+- output storage: Linux box local storage
+- workflow execution: ComfyUI on GPU box
+- public routing: `animatrix.desineuron.in` -> Linux box -> backend -> Comfy ingress -> GPU box
+
+This matters because Animatrix must not hardcode raw GPU IP assumptions in app logic.
+
+## 3. Current Live Workflow Truth
+
+Current production workflow truth:
+
+- primary live model path: `Wan 2.2 A14B`
+- current live animate workflow: `wan22_animate_move`
+- current implementation uses grounded start-frame image-to-video generation
+- current live aspect presets are injected into workflow inputs
+- current live duration presets are injected into workflow inputs
+
+What is live now:
+
+- start frame input
+- animate mode
+- audio performance mode surface
+- aspect ratio selection
+- duration selection
+- generation count selection from `x1` to `x4`
+- local Wan runtime model preflight against Comfy loader availability
+
+What is not yet live in production workflow terms:
+
+- true end-frame conditioning
+- exact start-to-end loop closure
+- guaranteed one-job-per-GPU scheduling semantics from the app layer
+- multiple production model families beyond Wan 2.2 A14B
+
+These items must remain explicit in the UI and docs. Animatrix should not fake capability.
+
+## 4. Why The Constraints Exist
+
+The application must stay narrow because Wan/Comfy workflows are brittle under drift.
+
+If the UI presents a control that has no faithful backend mapping, one of two things happens:
+
+- the backend ignores it, which is deceptive
+- the workflow fails unpredictably, which destroys trust
+
+The correct posture is:
+
+- expose only what is truly wired
+- label planned features as planned
+- keep the prompt surface clean
+- preserve reliability over option count
+
+## 5. UI Truth
+
+The Animatrix UI should behave like a focused generation console.
+
+That means:
+
+- prompt-first
+- minimal surrounding chrome
+- only active controls near the prompt
+- settings grouped into one compact options surface
+- frame and ingredient concepts visible
+- unsupported frame-end features marked as not yet live
+
+The target interaction model is closer to a modern studio composer than a dashboard CRUD form.
+
+## 6. Batch Generation Truth
+
+`x1` to `x4` in Animatrix means:
+
+- the frontend/backend submit 1 to 4 independent jobs
+- each job is a real backend job row
+- each job is a real Comfy submission
+
+What `x1` to `x4` does not guarantee on its own:
+
+- hard binding to four distinct GPUs
+- guaranteed parallel execution without runtime scheduler support
+
+Parallel execution depends on how the live Comfy/GPU runtime is configured.
+
+## 7. Known Critical Operational Truths
+
+The GPU runtime can appear healthy while still being unusable if model directories are empty.
+
+Therefore Animatrix now needs to assume:
+
+- workflow JSON validity is not enough
+- runtime loader availability must be checked against live Comfy object info
+
+This is part of production safety, not optional validation.
+
+## 8. Next Pass Targets
+
+The next pass of this document should append:
+
+- exact workflow inventory by mode
+- backend route truth
+- storage layout truth
+- deployment truth for Linux and GPU boxes
+- failure modes and recovery playbook
+- model hydration and verification truth