A motion design studio on your own machine

flowchart LR
  owner(["👤 Owner"])
  claude(["🤖 Claude session"])
  subgraph studio ["Mortiflix studio"]
    direction TB
    uc1(["Write a brief / start a project"])
    uc2(["Review a step: approve or ask for changes"])
    uc3(["Pin notes on frames, moments, paragraphs"])
    uc4(["Answer questions"])
    uc5(["Approve proposed error checks"])
    uc6(["Pause · resume · cancel"])
    uc7(["Do the step's work"])
    uc8(["Report status and progress"])
    uc9(["Submit at a gate (with checks)"])
    uc10(["Ask a question · propose a check"])
    uc11(["Queue a render"])
    uc12(["Hand off and stop"])
  end
  owner --- uc1 & uc2 & uc3 & uc4 & uc5 & uc6
  claude --- uc7 & uc8 & uc9 & uc10 & uc11 & uc12
        

Diagrams need the Mermaid library from cdn.jsdelivr.net (open this page online).

flowchart TB
  subgraph you ["For you"]
    cli["cli.mjs
bin/mortiflix"]
    web["web/server.mjs
+ web/app.js"]
  end
  subgraph sess ["For the session"]
    mfx["mfx.mjs
bin/mfx"]
    bridge["bridge.mjs
Unix socket, per-session token"]
  end
  subgraph core ["Core"]
    gates["gates.mjs
every rule"]
    projects["projects.mjs
record, events, journal"]
    pipelines["pipelines.mjs
load · validate · snapshot"]
    studio["studio.mjs
paths, config, secrets, locks"]
  end
  subgraph run ["Running sessions"]
    runner["runner.mjs
Runner"]
    torch["torch.mjs
workdir + CLAUDE.md"]
    renderq["renderq.mjs
RenderQueue"]
    subgraph backends ["backends/"]
      cc["claude-code"]
      api["anthropic-api"]
      demo["demo"]
    end
  end
  voice["voice/
index · elevenlabs · qwen"]

  cli & web --> gates
  cli & web --> runner
  cli & web --> voice
  mfx -- "JSON over socket" --> bridge
  bridge --> gates
  bridge --> renderq
  runner --> torch
  runner --> bridge
  runner --> renderq
  runner --> backends
  runner -- "settle()" --> gates
  demo -. "drives, like a session" .-> mfx
  gates --> projects --> pipelines
        

flowchart LR
  subgraph machine ["Your computer"]
    subgraph node ["Node process: mortiflix serve"]
      srv["Web server :4646
JSON API + SSE"]
      rn["Runner"]
      rq["RenderQueue"]
      br["Bridge
(per session)"]
    end
    browser["Browser
web studio"]
    sock[("Unix socket
OS temp dir")]
    claudecli["claude -p
(optional bubblewrap sandbox)"]
    tools["Remotion · ffmpeg · Chrome"]
    comfy["ComfyUI + Qwen3-TTS
(optional, GPU)"]
    fs[("Studio folder
~/Mortiflix")]
  end
  anth["Anthropic API"]
  eleven["ElevenLabs API
(optional)"]

  browser -- "HTTP + SSE" --> srv
  rn -- "spawns" --> claudecli
  claudecli -- "mfx" --> sock --> br
  rn -- "agent loop (API backend)" --> anth
  claudecli --> anth
  rq -- "spawns, one at a time" --> tools
  claudecli -. "vo.mjs" .-> eleven & comfy
  node --- fs
        

flowchart LR
  root["~/Mortiflix  ($MORTIFLIX_STUDIO)"]
  root --> cfg["config.json
settings, no secrets"]
  root --> sec["secrets.json (mode 600)
your keys, web token"]
  root --> env["session.env (mode 600)
other keys handed to sessions"]
  root --> chk["checks.json
the studio's error checklist"]
  root --> taste["TASTE.md
learned across projects"]
  root --> pl["pipelines/
your own (override built-ins)"]
  root --> projects["projects/‹id›/
working folder · session cwd"]
  root --> state["state/‹id›/
the record"]
  root --> runf["run/
runner lock, render logs, shared Remotion install"]
  projects --> w1["CLAUDE.md · JOURNAL.md · checklist.md"]
  projects --> w2["pipeline/ · .claude/skills/ · .mortiflix/GATES.md"]
  projects --> w3["input/ · feedback/ · out/ · video/"]
  state --> s1["project.json · events.jsonl"]
  state --> s2["pipeline/  (pinned snapshot)"]
  state --> s3["reviews/‹step›/v‹n›/  submission + copied files + feedback"]
  state --> s4["sessions/*.jsonl  transcripts + activity"]
  classDef rec stroke:#b18cff,stroke-width:2px;
  class state,s1,s2,s3,s4 rec;
        

classDiagram
  direction LR
  class Runner {
    +root
    +renders: RenderQueue
    +current
    +loop(watch, pollMs)
    +runSession(projectId)
    +stopProject(id)
    +stop()
    emits change, activity
  }
  class RenderQueue {
    -jobs: Map
    -order: id[]
    +add(projectId, sessionId, label, argv, cwd, env) id
    +wait(id, projectId, seconds) view
    +get(id, projectId) view
    +stopSession(sessionId)
    -pump()
  }
  class Backend {
    <<interface>>
    +name
    +available(config, root) bool
    +run(root, projectId, workdir, prompt, env, transcript, onActivity, signal, config) Result
  }
  class ClaudeCode {
    +sandboxArgs()
    +describeTool()
  }
  class AnthropicApi {
    +DEFAULT_MODEL
    +credentials(root)
    +editorTool()
    +confine()
  }
  class Demo
  class Shell {
    +run(command, timeout)
    +restart()
  }
  class UserError
  class GateError
  class ElevenLabs {
    +account() models() voices()
    +library() dictionaries()
    +speak(text)
  }
  class ComfyUI {
    +nodes() status()
    +queue(graph)
  }
  Backend <|.. ClaudeCode
  Backend <|.. AnthropicApi
  Backend <|.. Demo
  AnthropicApi *-- Shell
  Runner *-- RenderQueue
  Runner ..> Backend : runs one session at a time
  UserError <|-- GateError
  Error <|-- UserError
        

classDiagram
  direction LR
  class Project {
    id
    title
    pipeline (slug)
    backend?
    state
    answers
    steps: Map~key, StepRecord~
    questions: Question[]
    needs_you?
    no_progress
    without_gate
    usage
  }
  class StepRecord {
    state
    version
    last_feedback
  }
  class Pipeline {
    slug
    name
    makes
    shared_skills[]
    intake: IntakeField[]
    steps: PipelineStep[]
    status_lines
    checks: Check[]
  }
  class PipelineStep {
    key
    name
    review
    work[]
    after[]
    delivers
  }
  class Check {
    id
    title
    applies_to[]
    how
  }
  class Submission {
    note
    questions[]
    items[]
    error_checks[]
    pin_changes[]
  }
  class Feedback {
    verdict: approve|changes
    overall
    notes[]
    answers
  }
  class Note {
    text
    item?
    x?, y?
    time_sec?
    paragraph?
  }
  class Question {
    id
    text
    choices?
    default?
    answered_at?
  }
  Project "1" --> "1" Pipeline : pinned snapshot
  Project "1" *-- "*" StepRecord
  Project "1" *-- "*" Question
  Pipeline "1" *-- "1..*" PipelineStep
  Pipeline "1" *-- "*" Check
  StepRecord "1" --> "*" Submission : versions v1..vn
  Submission "1" --> "0..1" Feedback
  Feedback "1" *-- "*" Note
  Submission ..> Note : pin_changes answers each
        

stateDiagram-v2
  [*] --> draft : createProject
  draft --> queued : startProject (required intake answered)
  queued --> waiting : settle - a step is in review or a question is open
  waiting --> queued : you approve / ask for changes / answer
  queued --> delivered : settle - every step finished
  queued --> paused : no progress twice, 8 sessions without a gate, needs-you
  queued --> paused : you pause
  waiting --> paused : you pause
  paused --> queued : you resume
  draft --> cancelled : you cancel
  queued --> cancelled : you cancel
  waiting --> cancelled : you cancel
  paused --> cancelled : you cancel
  delivered --> [*]
  cancelled --> [*]
        

stateDiagram-v2
  [*] --> blocked
  blocked --> ready : every step in "after" is finished
  ready --> working : mfx step start / first work
  working --> in_review : mfx submit (reviewed step)
  ready --> in_review : mfx submit
  in_review --> approved : you approve
  in_review --> changes : you ask for changes
  changes --> in_review : next version, every note answered
  working --> done : mfx step done --checks (internal step)
  approved --> [*]
  done --> [*]
  note right of blocked : derived states (blocked, ready) are computed by stepView; the rest are stored
        

stateDiagram-v2
  [*] --> waiting : mfx render
  waiting --> running : pump() - nothing else running
  running --> done : exit 0
  running --> failed : exit ≠ 0
  waiting --> failed : session ended
  running --> failed : session ended (SIGTERM to the group)
  done --> [*]
  failed --> [*]
        

sequenceDiagram
  autonumber
  participant R as Runner
  participant T as torch.mjs
  participant B as Bridge
  participant K as Backend
  participant S as Claude session
  participant M as mfx
  participant G as gates.mjs
  R->>R: next queued project
(oldest queued_at)
  R->>T: prepareWorkdir
(pinned pipeline, skills, GATES.md)
  R->>T: writeTorch → CLAUDE.md
  R->>B: openBridge (Unix socket + token)
  R->>K: run(prompt "Read ./CLAUDE.md…",
env MFX_SOCKET / MFX_TOKEN)
  K->>S: start
(claude -p or the API agent loop)
  loop until it reaches a gate
    S->>M: mfx status / checks / render …
    M->>B: POST {command, args, token}
    B->>G: same function, same rules
    G-->>S: result, or a refusal
as a plain sentence
  end
  S->>M: mfx submit step submission.json
  M->>B: submit
  B->>G: submit(): validate,
copy files into state/
  S->>M: mfx handoff "…"
  S-->>K: ends its turn
  K-->>R: {ok, usage, cost_usd}
  R->>R: stop leftover renders,
close bridge
  R->>G: settle() →
waiting · queued · delivered
  R-->>R: guards: pause after 2 no-progress
sessions or 8 without a gate
        

sequenceDiagram
  autonumber
  actor O as Owner
  participant W as Web studio / CLI
  participant G as gates.mjs
  participant FS as Studio folder
  participant R as Runner
  participant S as Next session
  O->>W: pin notes (frame x,y · moment · paragraph)
verdict "changes"
  W->>G: respond(step, version,
{verdict, overall, notes, answers})
  G->>G: step must be in_review at that version,
notes must point at real items
  G->>FS: state/…/feedback.json
projects/…/feedback/step-vN.json
  G->>G: step → changes, settle → queued
  G-->>W: SSE "change"
  R->>S: new session
(CLAUDE.md summarizes the notes)
  S->>S: sort each note:
error or taste, fix both
  opt an error no check would have caught
    S->>G: mfx propose-check
(approved once, every future video runs it)
  end
  S->>G: mfx submit v(N+1)
pin_changes: one entry per note
  G-->>O: back in review,
with what changed per note
        

flowchart TB
  start(["mfx submit step submission.json"]) --> internal{"step is internal?"}
  internal -- yes --> r1["refuse: use mfx step done --checks"]
  internal -- no --> note{"has a note?"}
  note -- no --> r2["refuse"]
  note -- yes --> qs{"questions valid?
text, unique ids, default ∈ choices"}
  qs -- no --> r3["refuse"]
  qs -- yes --> items{"every item: exists, a file,
inside the project (symlinks resolved)?"}
  items -- no --> r4["refuse"]
  items -- yes --> mode{"review mode satisfied?
frames→images · video→video · document→text"}
  mode -- no --> r5["refuse"]
  mode -- yes --> checks{"every check for the step's work
reported? fixed / n/a have a note?"}
  checks -- no --> r6["refuse"]
  checks -- yes --> lock["under the project lock"]
  lock --> st{"step state ok?
not blocked, not in review, not approved"}
  st -- no --> r7["refuse"]
  st -- yes --> pins{"last version had notes?
one pin_changes entry each, with a change and a status"}
  pins -- no --> r8["refuse"]
  pins -- yes --> copy["copy files into state/…/reviews/step/vN/
write submission.json"]
  copy --> done(["step → in_review · event SUBMITTED · settle"])
        

sequenceDiagram
  participant S as Session
  participant B as Bridge
  participant Q as RenderQueue
  participant P as Remotion / ffmpeg
  S->>B: mfx render --label "animatic"
-- npx remotion render …
  B->>Q: add(job)
  Q-->>S: {id: 3, state: waiting, renders_ahead: 1}
  Q->>Q: pump(): previous job finished
  Q->>P: spawn (own process group, log file)
  S->>B: mfx render-wait 3
  B->>Q: wait(3, 100 s)
  P-->>Q: exit 0
  Q-->>S: {state: done, output_tail}
  Note over S,Q: when the session ends, its waiting and running jobs are stopped
        

flowchart LR
  brief["Brief
questions"]
  script["Script
document · script"]
  frames["Style frames
frames · stills"]
  animatic["Animatic
video · motion, audio"]
  build["Build
internal · motion, audio"]
  final["Final
video · delivers"]
  brief --> script & frames
  script & frames --> animatic --> build --> final
  classDef you stroke:#ff8fd1,stroke-width:2px;
  class brief,script,frames,animatic,final you;