How the system works — and where to make changes in each thing.

Five layers, one rule

The rule that underpins the design is written at the top of the src/fluxos/runtime.ts: the orchestrator doesn’t do the work, and the worker doesn’t make decisions. THE SIX STEPS OF montar-reel.py done/failed; the runtime reads this and chooses the next phase — doing so within the same ack transaction, so “phase completed” and “next phase queued” never exist separately.

The bot knows nothing about video

This is the boundary that lets the system grow without getting bloated. The bot knows about queues, gates, retries, and delivery. The domain knows about audiences, prompts, templates, and the rendering engine. They meet in exactly two files.

When the file is read

What’s ready, and what’s intentionally missing

A flow isn't a script that runs from top to bottom. It's a definition that is frozen when it's created, then advances phase by phase, with the state in the database. This is what lets you restart the process midway and pick up where it left off.

The four concepts that explain any workflow: flow.json

promoavatar — one video per audience

The format is 12 targets (one per audience), prefix A, seven phases, four of which are alternative optional routes for producing the same avatar.

promoavatar3 — three videos per audience

The reel engine—one engine, N domains <publico>-<tipo>: 12 audiences × 3 types = 36 targets, prefix C. It gained prompt variants, CTA by variant, and the layout map — and lost the route navega-avatar.

promoavatar vs promoavatar3

The engine is deliberately dumb on the bot side and smart on the domain side. That’s what lets you change the look of all reels by editing one JSON file, without recompiling anything.

The phase reel doesn’t render anything: it builds a command line and launches a detached process. All rendering lives in Python, in the domain repo — and one domain can point to another domain’s engine with motor_repo, instead of copying the scripts.

I want to change X—where do I edit it?

The table that answers 90% of questions from people who arrive at the system. The right-hand column says whether the process needs to be restarted.

A new domain, from scratch, without touching the bot

This is the test that the boundary is in the right place. If your new domain requires editing TypeScript, either it needs a task that doesn’t exist or the boundary has leaked.

# 1. the domain repo, alongside the bot
mkdir ~/projetos/meudominio && cd ~/projetos/meudominio

# 2. flow.json — targets, phases, and the engine for another repo
cat > flow.json <<'JSON'
{
  "nome": "meudominio", "prefixo": "M", "versao_def": 1,
  "motor_repo": "promoavatar3",
  "templates_dir": "templates", "template": "empilhado-capa",
  "alvos": { "ep01": { "canal": "lives2", "fecho": "..." } },
  "fases": [
    { "id": "texto", "escopo": "fluxo", "fila": "texto",
      "kind": "agent", "tarefa": "fluxo-agente",
      "prompt": "prompts/fase1.md", "pausa_apos": true },
    { "id": "reel", "escopo": "alvo", "fila": "render",
      "kind": "function", "tarefa": "reel.montar" }
  ]
}
JSON

# 3. register it in the bot — the ONLY step that requires a restart
#    config/fluxos.json:  {"command":"meudominio","repo":"meudominio",...}

# 4. test WITHOUT spending an avatar or render
/meudominio assunto de teste | sombra

The decisions that make this system work

These aren’t implementation details—they’re the choices that prevented entire classes of bugs and apply to any agent-based queue system.

What needs to be in place

Phase barrier, job preemption, global agent limit, and multi-user support. Each omission has a documented trigger for reconsideration. A system that starts with everything is a system no one finishes.