O que você vai aprender#
- o que cada pasta de nível superior guarda;
- onde pertence uma regra, um adaptador ou uma página;
- quais pastas são geradas e nunca editadas à mão.
A ideia#
Há um repositório e um módulo Go. As pastas seguem uma regra: a lógica de edição vive em core/, todo o resto é um adaptador ou uma camada de apoio em volta dele. Uma mudança vai onde a sua regra vive, e os adaptadores continuam finos.
| Pasta | Guarda |
|---|---|
core/ | o núcleo de comandos: o documento da linha do tempo, os comandos, as regras de verificação (lint), o plano de renderização, o tempo. Go puro, sem E/S |
engine/ | o que toca a mídia: ingestão, o FFmpeg como processo separado, o rasterizador que compõe pixels, exportação, transcrição, o armazenamento endereçado por conteúdo |
service/ | a única fronteira de serviço: projetos, tarefas, persistência, o bloqueio do espaço de trabalho, configuração, limites, o doctor |
web/app/ | os adaptadores sobre o serviço: a API HTTP, o servidor MCP (mcp/), a CLI (cli/), autenticação, eventos |
web/cmd/ | o programa: serve, mcp, open, user:create e o gerador do material para agentes |
web/resources/ | o editor no navegador (TypeScript, um cliente fino) |
web/contract/ | os testes de contrato que acionam as cinco superfícies e comparam os documentos que elas produzem |
site/ | este site de documentação e a página de apresentação |
desktop/ | a casca de desktop, que vem depois |
docs/ | requisitos (prds/), decisões de arquitetura (adrs/), especificações (sdds/) e pesquisa |
internal/ | ferramentas que rodam no repositório, como os geradores de código |
scripts/ | scripts de shell da versão e da imagem |
licenses/, THIRD_PARTY_NOTICES.md | as licenças do que é distribuído; geradas ou mantidas à mão como o guia de contribuição diz |
.github/, .config/ | workflows, modelos, a definição da imagem e a configuração das ferramentas |
Início rápido#
- Encontre a regra. Uma nova operação de edição é um comando em
core/command/, descrito no catálogo de comandos (docs/sdds/002-command-catalogue.md); o seu nome vem das definições compartilhadas. - Alcance-a pelos adaptadores. A ferramenta MCP, o comando da CLI e a rota HTTP chamam o mesmo método do serviço; eles não acrescentam nenhuma regra.
- Mostre-a no editor em
web/resources/, que apenas desenha e envia comandos. - Regenere o que deriva dela com
task codegen, e a referência do site comnpm run referenceemsite/.
Erros comuns#
- Escrever uma regra em um handler, uma ferramenta ou em TypeScript. O
bun run check:thin-cliente a revisão a rejeitam. - Editar uma saída gerada:
core/schema/,web/resources/js/generated/,site/generated/,site/content/generated/einternal/ffmpegpins/vêm dotask codegene dos geradores do site. - Colocar E/S em
core/: ele precisa continuar puro para que a pré-visualização e a exportação concordem. - Tratar um spike como código do produto. Os experimentos em
spikes/são descartáveis e nunca são promovidos.