Ordo

Arquitetura

1. Cliente

   POST /jobs com receita + artefatos
2. Ordo

   valida · armazena · rastreia estado
3. Workers n8n

   reivindica etapa · roda ferramenta · registra artefato
4. Object storage

   artefatos em MinIO / S3
5. Finalizador

   entrega saídas · hook on_exit

Por que existe

Construí o Ordo enquanto construía o Skyport. O n8n era excelente para executar etapas e integrar sistemas, mas o pipeline vivia precisando de garantias que o n8n não dava: que as entradas de um job fossem válidas antes da primeira etapa rodar, que as saídas de uma etapa batessem com o que a próxima esperava, que um job falho deixasse um rastro claro do que foi e do que não foi produzido. Eu queria algo que ficasse acima da execução, continuasse simples e ainda assim fosse rigoroso.

O modelo

Uma receita é uma lista de etapas. Cada etapa nomeia um tipo de executor, mapeia os slots de entrada do executor para referências de artefato com namespace (job:<nome> para entradas do job, step:<id>.<slot> para saídas de etapa) e mapeia seus slots de saída para nomes de artefato. Executores são linhas em uma tabela step_executor declarando o que aceitam e produzem; a validação da receita confere que todo tipo de etapa existe, todo slot está ligado exatamente uma vez, todo artefato referenciado é produzível e nenhum nome de artefato se repete. Parâmetros são declarados nas receitas só por chave e fornecidos por job, então valores de parâmetro nunca afetam a identidade de uma receita.

Jobs são criados a partir de uma receita mais artefatos de entrada concretos, parâmetros e declarações opcionais de saída. O Ordo insere a fila de etapas, expõe o progresso como fração entre as etapas, mostra a última linha de log de cada etapa e roda uma etapa on_exit depois que o grafo principal termina, independentemente do resultado. Um max_concurrency por etapa limita quantas instâncias de um executor rodam ao mesmo tempo entre todos os jobs.

Fronteiras e próximos passos

O Ordo não executa etapas, não gerencia infraestrutura, não oferece editor nem move arquivos. Workers n8n reivindicam etapas direto do banco, executam a ferramenta, registram artefatos e reportam status; um workflow finalizador separado entrega as saídas declaradas ao seu caminho final de storage. Esse contrato direto com o banco é pragmático, não fundamental, e o roadmap é desacoplá-lo atrás de filas ou APIs para que vários backends de execução rodem lado a lado.

A API é um pequeno serviço TypeScript/Express sobre PostgreSQL com migrações aplicadas na inicialização, lançado via semantic-release e distribuído como imagem Docker.