sagnik/Project_Animatix

Fork 0

Files

Sagnik c7994d17a9 Initial Animatrix import

2026-04-17 19:11:57 +05:30

16 KiB

Raw Blame History

Animatrix Build Prompt for Coding Agent - First Principles

Date: 2026-04-15

Purpose

This document is a direct implementation prompt for a coding agent. The agent should use this prompt to build Animatrix end to end as a production-oriented full-stack product.

This prompt is intentionally monolithic and explicit. The objective is to minimize ambiguity, reduce design drift, and make the output directly integrable into the repository with minimal reinterpretation.

How To Use This Prompt

Give this entire document to the coding agent as its working brief. The agent should treat this document and the existing Animatrix SRS as the primary source of truth. The agent must build the application directly, not merely discuss architecture.

Companion source of truth:

[Animatrix Monolithic SRS - Wan 2.2 Flow Studio.md](F:\Workin In Progress\DESINEURON\GITLAB\Animatrix\Animatrix Monolithic SRS - Wan 2.2 Flow Studio.md)

Infrastructure truths that must be respected:

[comfyui_setup_truth.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\comfyui_setup_truth.md)
[Desineuron Stable Ingress Handoff.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Desineuron Stable Ingress Handoff.md)

Copy-Paste Prompt For The Coding Agent

You are implementing a new full-stack product called Animatrix inside the repository root at F:\Workin In Progress\DESINEURON\GITLAB\Animatrix.

You are not writing a concept note. You are building the actual implementation skeleton and as much of the product as possible in production shape.

Your mission is to build Animatrix end to end as a full-stack application with:

frontend
backend API
simple database-backed authentication
upload pipeline
ComfyUI workflow orchestration
job persistence
result gallery
operator-safe integration with the live Desineuron stack

You must reason from first principles, but you must implement concrete code rather than remaining abstract.

Product Definition

Animatrix is a focused product for guided character video generation using the Wan 2.2 family through ComfyUI.

It is not a general-purpose ComfyUI editor.

It exposes exactly two production workflows in v1:

Animate Studio
- powered by Wan2.2-Animate-14B
- supports Move and Mix
- inputs: prompt, ground-truth image, motion video, optional references, optional pose sheet
Audio Performance Studio
- powered by Wan2.2-S2V-14B
- inputs: prompt, ground-truth image, audio, optional references, optional pose sheet

The product must provide a frontend similar in spirit to Google Flow:

simple prompt composer
image chips for attachments
plus button to add optional assets
compact right-side mode switch
one-click generation

The product must not expose raw ComfyUI nodes to end users.

Non-Negotiable Truths

You must respect the actual model capability split:

Wan2.2-Animate-14B handles character animation and character replacement
Wan2.2-S2V-14B handles audio-driven video generation
exact first/last-frame control is not part of the first release
pose sheet support in v1 is soft guidance, not full deterministic control-video behavior

You must respect the existing Desineuron infrastructure:

ComfyUI already exists and is exposed through https://comfy.desineuron.in
Do not connect to a raw GPU public IP
Do not hardcode the current GPU private IP
Treat https://comfy.desineuron.in as the execution dependency

You must respect the current ops posture:

NVMe is used for model/runtime storage on GPU
ingress and TLS already exist
this product should sit cleanly on top of that system

Implementation Goal

Build a repository-local full-stack application in Animatrix/ with a structure that a team can continue directly.

The result must be implementation-grade, not pseudo-code.

You should build:

frontend app
backend app
data models
database migrations or schema bootstrap
authentication layer
upload endpoints
ComfyUI client wrapper
workflow template binding layer
job runner
result persistence
UI pages
configuration examples
README or runbook

Required Stack Choice

Default to the following unless the repository already strongly dictates otherwise:

frontend: Next.js with TypeScript
backend: FastAPI with Python
database: SQLite for local/dev and clean migration path to PostgreSQL later
auth: simple email/password login with session cookie or JWT-based auth, but keep it simple
ORM: SQLAlchemy or SQLModel on backend
storage:
- local filesystem for dev
- abstraction for S3-compatible storage later

Reasoning:

Next.js gives a fast frontend delivery path
FastAPI gives good async/media handling and aligns with the current Python-heavy ops environment
SQLite reduces bootstrap friction for immediate delivery
the design must preserve clean upgrade paths to PostgreSQL and S3

Do not overengineer with microservices in v1.

Required Repository Structure

Create a clean structure under Animatrix/ similar to:

Animatrix/
  frontend/
  backend/
  workflows/
  docs/
  scripts/
  infra/
  .env.example
  README.md

Inside that:

frontend/
  src/
    app/
    components/
    features/
    lib/
    styles/

backend/
  app/
    api/
    core/
    db/
    models/
    schemas/
    services/
    repositories/
    workers/

Create this structure if it does not exist.

Product UX Requirements

The frontend must support:

login page
registration page
authenticated dashboard
create-job composer
upload chips
mode switch between Animate and Audio
advanced settings drawer
job history list
individual result page

The composer must support:

prompt text
ground-truth image upload
optional reference image uploads
optional pose sheet upload
motion video upload for Animate mode
audio upload for Audio mode
mode-specific validation

UI behavior requirements:

keep the screen minimal
no enterprise CRUD feel
no purple default design
intentional, dark, focused creative-tool aesthetic is acceptable
avoid generic admin-dashboard look

Backend Requirements

Build a backend API that supports:

auth
asset upload
asset metadata lookup
job creation
job status query
job output query
admin queue introspection

Required API groups:

/api/auth/*
/api/assets/*
/api/jobs/*
/api/admin/*

Required core flows:

user logs in
user uploads assets
backend stores assets and metadata
user submits a generation job
backend validates mode-specific requirements
backend selects workflow template
backend uploads required assets to ComfyUI
backend submits prompt JSON to ComfyUI
backend tracks prompt ID and execution state
backend collects final outputs and persists them
frontend shows status and outputs

Authentication Requirements

Implement a simple but real database-backed auth layer.

Minimum requirements:

registration with email and password
password hashing
login
authenticated session
logout
user-job ownership relation

Keep the auth simple. Do not bring in OAuth or external identity providers in v1 unless there is a compelling reason.

If you use JWT, store it safely. If you use cookie sessions, configure them properly.

Preferred outcome:

email/password auth
hashed passwords with passlib or equivalent
server-side session or signed JWT cookie

Database Requirements

Implement a database with at least these tables or equivalent models:

users
assets
jobs
job_outputs
job_events

Suggested minimum fields:

users

id
email
password_hash
created_at
updated_at

assets

id
owner_id
asset_type
mime_type
original_filename
storage_path
thumbnail_path
size_bytes
width
height
duration_seconds
created_at

jobs

id
owner_id
mode
submode
prompt
negative_prompt
status
comfy_prompt_id
workflow_template_name
workflow_template_version
settings_json
created_at
updated_at

job_outputs

id
job_id
output_type
file_path
poster_path
metadata_json
created_at

job_events

id
job_id
event_type
message
payload_json
created_at

Use migrations or a bootstrapping strategy that is clean and rerunnable.

Storage Requirements

Implement a storage abstraction rather than hardcoding one persistence model everywhere.

For v1:

local filesystem storage is acceptable

But build the code so it can later support:

S3 object storage for uploads
S3 object storage for outputs

You must create service boundaries for:

asset storage
output storage
thumbnail generation

ComfyUI Integration Requirements

Implement a clean ComfyUI client service.

It must be the only layer that talks directly to:

POST /prompt
GET /history/{prompt_id}
GET /queue
POST /upload/image

If needed, also support video or audio uploads using the proper Comfy-compatible upload handling strategy in your backend integration path.

Design a service like:

ComfyClient
WorkflowBinder
JobOrchestrator

The backend must never scatter raw requests across multiple files.

Workflow Requirements

Create versioned workflow template placeholders under:

workflows/animate/
workflows/s2v/
workflows/shared/

Even if the exact final production JSON is not fully available yet, create the binding architecture properly now.

You must implement:

template loading
parameter injection
node ID mapping
workflow version metadata

The system must support:

Wan2.2-Animate-14B for move and mix
Wan2.2-S2V-14B for audio-driven generation

Do not fake support for first/last-frame workflow in v1.

Job Execution Model

Implement an execution model that is supportable.

Minimum acceptable design:

create job record in DB
perform async orchestration
update job status as it moves through states

Use explicit statuses:

created
validating
uploading_assets
queued
executing
collecting_outputs
completed
failed

If background jobs are needed, choose a simple and supportable path. Acceptable examples:

FastAPI background tasks for MVP
a simple worker loop
lightweight task queue if necessary

Do not pull in a large distributed system unless it materially improves delivery.

Frontend Requirements in Detail

Build a polished frontend that includes:

Main dashboard behavior

The dashboard should have:

a main creation composer at the top
recent outputs or job history below
simple filter between All, Animate, and Audio

Composer behavior

The composer should allow:

prompt entry
attachment chip previews
plus button to add more attachments
mode switch
advanced settings panel
submit button

Visual design

Design it as a creative tool:

dark, cinematic, focused
strong spacing and clean hierarchy
rounded attachment chips
non-generic toggle controls
clear submit affordance

Do not build a dull form-driven admin UI.

API and UI Contract

The frontend must not send raw files straight into a final job call.

Preferred flow:

upload assets first
receive asset IDs
create job with asset IDs and settings

The job creation payload should clearly map to workflow mode.

Validation Requirements

You must enforce:

Shared

prompt presence if required
ground-truth image required

Animate mode

motion video required
move or mix required

Audio mode

audio required

Optional inputs

reference images optional
pose sheet optional

Treat pose sheet as reference guidance in metadata, not as deterministic control.

Result Delivery Requirements

Each completed job should produce:

main video result
poster or thumbnail
metadata record

The frontend job page should show:

current status
prompt
attached assets summary
output preview
download link

Required Documentation Deliverables

While implementing, also create:

top-level README.md
backend .env.example
frontend .env.example if needed
a short RUNBOOK.md or equivalent setup section in README

The documentation must explain:

how to run backend
how to run frontend
what env vars are needed
how ComfyUI host is configured

Environment Configuration Requirements

Design configuration for:

backend base URL
frontend base URL
database URL
asset storage root
output storage root
ComfyUI base URL
session secret or JWT secret

Use env vars.

Do not hardcode production hostnames directly in the implementation logic.

Integration Constraints

You must build this so it can later integrate cleanly into the wider Desineuron stack.

That means:

no breaking assumptions about direct GPU access
no hidden dependency on localhost-only ComfyUI
no assumption that the frontend and backend must share one process
no brittle absolute-path assumptions in core business logic

Coding Style Constraints

keep modules small and purposeful
avoid giant god-classes
use typed request and response schemas
use explicit service boundaries
use reusable validation helpers
keep file names and routes clear

What Not To Do

Do not:

build a fake prototype with no real backend
expose raw ComfyUI workflows to users
pretend one Wan model does everything
hardcode temporary machine IPs
design a node-editor frontend
skip auth because it is "only MVP"
overcomplicate with Kubernetes, event buses, or multi-service orchestration in v1

Expected Output From This Task

At the end of implementation, you should have produced:

a working full-stack Animatrix codebase under Animatrix/
a login flow
a functional dashboard UI
upload and job creation API
database models and initialization
ComfyUI integration layer
workflow-binding layer
job status and result views
setup documentation

If a portion cannot be fully completed because exact production workflow JSON files are still pending, then:

implement the surrounding infrastructure completely
create strict template placeholders
document exactly what needs to be dropped in later
do not leave the architecture vague

Execution Plan You Should Follow

Create repository structure.
Scaffold backend with config, DB, auth, and API layout.
Scaffold frontend with login, dashboard, and job pages.
Implement asset upload and storage services.
Implement ComfyUI client wrapper.
Implement workflow binder and mode selection logic.
Implement async job orchestration and status persistence.
Implement output persistence and result views.
Add documentation and environment examples.
Verify the project boots locally in a clean development flow.

Final Rule

You are expected to produce real code, not a design memo.

Where a hard production dependency is missing, build the complete surrounding system and leave a narrow, explicit seam rather than handwaving.

Operator Note

This prompt is intentionally designed to make the coding agent behave like an implementation engineer rather than an ideation partner.

The correct next use of this file is:

bring this file into the coding agent context
also provide the Animatrix SRS
instruct the agent to implement directly in Animatrix/

Recommended Pairing Prompt

If you want a shorter launcher prompt to accompany this file, use:

Use the attached Animatrix build prompt and Animatrix SRS as the source of truth. Implement the full-stack product directly inside the Animatrix folder. Build the frontend, backend, DB-backed auth, asset upload pipeline, workflow binding layer, ComfyUI integration, job tracking, and result pages. Do not stop at planning. Write the code and docs.

16 KiB Raw Blame History