# 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