Como navegar¶
Documentação como código do monorepo Garantora — SaaS B2B de gestão de garantias imobiliárias. Tudo que descreve o quê e por quê do produto e da plataforma vive aqui, em Markdown, versionado junto com o código que descreve.
Se você procura como o código está organizado hoje, comece pelo CLAUDE.md de cada app (apps/api/CLAUDE.md, apps/web/CLAUDE.md, apps/e2e/CLAUDE.md) — esses arquivos guiam quem (humano ou IA) vai trabalhar na árvore do repositório e não foram movidos para cá. Esta documentação é o registro do que foi decidido e construído: a dor de cada funcionalidade, a correção de cada defeito, a arquitetura resultante.
Onde entrar¶
| Se você quer... | Vá para |
|---|---|
| Entender o domínio (quem é garantidora, imobiliária, inquilino) | product/glossary.md |
| Ver as regras de negócio centrais | product/business-rules.md |
| Ler uma funcionalidade específica, como foi pedida e desenhada | specifications/ |
| Ver um defeito corrigido, sintoma → causa → correção | fixes/ |
| Saber o que já existe, o que falta e o que está pendente de decisão | roadmap.md |
| Ver ajustes pequenos antigos (histórico — o ajuste direto hoje não gera documento) | tweaks/ |
| Entender a arquitetura do sistema (containers, dados, deploy) | architecture/ |
| Ver por que uma decisão estrutural foi tomada | decisions/ |
| Consultar o contrato da API | api/ |
| Rodar o repositório na sua máquina e entender como o trabalho entra | getting-started/ |
| Rodar, publicar ou diagnosticar a plataforma | operations/ |
| Escrever uma spec, fix ou ADR nova | doc-templates/ e operations/documentation-platform.md |
| Você é um agente de IA chegando aqui pela primeira vez | ai-guide.md |
Como isto nasceu¶
Até 2026-08-30 a documentação estava espalhada em spec/, fix/, tweak/ (na raiz do repositório) e num docs/ pequeno, com quatro arquivos soltos de design. Esta árvore unifica tudo isso — ver decisions/ADR-0004-documentacao-como-codigo.md para o porquê, e metadata/migration-map.yaml para o mapeamento completo de onde cada documento estava e para onde foi.
Convenções¶
- Português é a língua de todo o conteúdo de negócio e produto (specs, fixes, glossário, roadmap) — é a língua em que o time e o domínio pensam. Documentação puramente técnica de plataforma pode aparecer em inglês quando fizer sentido (nomes de arquivo, termos de infraestrutura), mas o texto corrido segue em português.
- Front matter YAML identifica tipo, status e relações de todo documento que participa do catálogo (
metadata/catalog.yaml) — ver o schema emmetadata/README.md. - IDs são estáveis e nunca reciclados:
SPEC-NNNN,FIX-NNNN,ADR-NNNN. Specs e fixes preservam a numeração histórica de quando viviam emspec//fix/. - Como o trabalho anda — desde 2026-10-15 o plugin Superpowers conduz funcionalidade e defeito (os skills
/spec,/fixe/tweakforam removidos), e o registro continua aqui, emspecifications/efixes/; o ajuste direto não gera documento. A fonte é a seção Fluxo de desenvolvimento doCLAUDE.mdda raiz — resumo emgetting-started/development.md. - Diagramas são código. Mermaid para fluxo, jornada, sequência, estado e entidade; Structurizr DSL para C4 quando o diagrama precisa de mais de uma vista consistente.