003 — Plan · Fundação: Monorepo, Documentação e Pipeline de PDF

Data: 2026-06-29

Contexto

Todo projeto repete o mesmo setup e a mesma metodologia. Centralizar a fundação num boilerplate — monorepo, manifesto embutido, documentação viva, site de docs e geração de PDF — elimina retrabalho e garante conformidade com o Manifesto desde o início. A stack da aplicação (OpenAPI, estado, UI, testes, banco) é tratada à parte, na ADR 002.

Decisão

Montar um monorepo Turborepo (apps/*, packages/*) com o manifesto/ versionado dentro e a .specs/ como documentação viva. Publicar manifesto + .specs num site Astro Starlight (tema Astra) e gerar PDFs das ADRs com identidade visual própria. Fornecer um script para iniciar projetos novos desacoplados do git do boilerplate.

Consequências

Positivas: bootstrap quase instantâneo; uma fonte de verdade (Markdown) para site e PDF.
Custos: manter a fundação em dia com o manifesto; projetos derivados desacoplam o git.

Tarefas e subtarefas

Migrar o manifesto/ para o monorepo (identidade visual definida; docs/ → .specs/).
Criar .specs/ (esta ADR, a ADR 002, exemplo didático, notes).
Pipeline de PDF (ADR e manifesto) com identidade visual própria.
Site de documentação (Astro Starlight, tema Astra) com sync de manifesto + .specs.
Scripts de orquestração e init-project.
Identidade visual (logo).

Quiz de decisões

Tema: Monorepo e estrutura

P1. Onde montar o boilerplate?

( ) A) Repositório novo do zero.
(X) B) Sobre o scaffold Turborepo existente (apps/web + packages/ui, estilo radix-nova).
( ) C) App Next.js único, sem monorepo.

Justificativa: o scaffold já traz Turborepo, pnpm workspaces, shadcn radix-nova e os pacotes compartilhados. Reaproveitar evita refazer trabalho.

P2. Onde fica a documentação do projeto?

( ) A) docs/ (convenção original do manifesto).
(X) B) .specs/ (separa metodologia de documentação viva).
( ) C) Dentro de apps/docs.

Justificativa: pedido explícito. O manifesto foi adaptado para a nova convenção (docs/ → .specs/) sem perder conteúdo.

Tema: PDF

P3. Como gerar os PDFs das ADRs?

(X) A) md-to-pdf (Puppeteer) — o mesmo padrão dos projetos de referência.
( ) B) @react-pdf/renderer (componentes React).
( ) C) Serviço externo (Browserless).

Justificativa: é exatamente o que os projetos de referência usam (scripts generate-tecnico): um PDF por arquivo + consolidado + resources, cabeçalho/rodapé de marca, Mermaid. Sem serviço externo, copiável e offline.

Tema: Site de documentação

P4. Qual tema do Starlight?

(X) A) starlight-theme-nova (o “tema Astra”).
( ) B) Starlight padrão só com cores customizadas.

Justificativa: pedido explícito do tema Astra. Cores de acento aplicadas por cima via custom.css.

P5. O site renderiza só o manifesto?

( ) A) Só o manifesto.
(X) B) Manifesto e .specs/ (documentação viva), em seções separadas na sidebar.

Justificativa: o pedido foi renderizar “manifesto + documentação viva de .specs”. O sync-docs.mjs sincroniza as duas fontes, ignorando notes/ e pdf/.

Tema: Git

P6. Quão rígidas são as regras de git no boilerplate?

( ) A) Fluxo rígido com PRs obrigatórios.
(X) B) Flexível: trabalhar direto na develop, sem exigir PR.

Justificativa: pedido do dono do projeto. O capítulo de git do manifesto e o CLAUDE.md foram suavizados — develop é a branch de trabalho; PR é opcional.

Tema: Reuso do boilerplate

P7. Como iniciar um projeto novo a partir daqui?

( ) A) Commitar direto neste repositório.
(X) B) Script init-project que apaga o git do boilerplate e inicia um repo novo.

Justificativa: o boilerplate é ponto de partida, não destino. pnpm init desacopla o git e conecta a um remoto novo.

Pós-plan

Riscos: drift entre boilerplate e libs; mitigado por scripts e CI futuro.
Dependências: Chromium (Puppeteer) para PDF.
Fora de escopo: OpenAPI/estado/UI/testes (ADR 002), deploy, auth.

Criado por Joseph Trupel