Busca-Busca — Documentação (docs-first)

Repositório de documentação do Busca-Busca, uma plataforma para centralizar a busca, o filtro e a pré-análise de imóveis em leilão (começando pela Caixa), com cálculo de custos (ITBI, custas, etc.) e evolução para análise assistida por IA.

Abordagem docs-first: primeiro documentamos objetivo, regras de negócio, arquitetura e decisões; o código nasce a partir daqui. Esta é a fonte única da verdade do projeto.

Markdown como fonte única. A documentação é markdown puro, para ler direto no GitHub/editor e ser facilmente compreendida por pessoas e por agentes de IA (ver ADR-0004). Opcionalmente, há um portal navegável gerado a partir desses mesmos .md — veja Portal de documentação abaixo.

Índice

O índice canônico da documentação fica em docs/ — comece por lá. Novo no projeto? Veja os Primeiros passos.

Entradas por tema (cada pasta abre seu README.md automaticamente no GitHub):

Tema	Entrada
Visão geral	docs/visao-geral/
Produto	docs/produto/
Arquitetura	docs/arquitetura/
Domínio	docs/dominio/
Contratos	docs/contratos/
Dados	docs/dados/
Serviços	docs/servicos/
Infraestrutura	docs/infraestrutura/
Observabilidade	docs/observabilidade/
Qualidade	docs/qualidade/
Legal & conformidade	docs/legal/

Estrutura de pastas

Cada pasta temática tem um README.md como página de entrada (renderiza sozinho ao abrir a pasta).

docs/
  README.md                    # índice canônico (porta de entrada)
  visao-geral/                 # objetivo, primeiros passos, glossário, roadmap
  produto/                     # requisitos, features, estudos de caso, rastreabilidade
  arquitetura/                 # visão, stack, ferramentas, diagramas e ADRs (decisões)
  dominio/                     # regras de negócio, cálculo de custos, pré-análise
  contratos/                   # API de ingestão (OpenAPI) e eventos RabbitMQ
  dados/                       # modelo de dados e a fonte Caixa (CSV/detalhe)
  servicos/                    # backend (Java), collector (Python), frontend (Angular)
  infraestrutura/              # Docker (dev), repos, k3s/GitOps, rede, config/segredos, backup, registry
  observabilidade/             # métricas/logs/traces, SLO, AIOps (MCP), runbooks
  qualidade/                   # testes, CI/CD, segurança
  legal/                       # LGPD, termos de uso, conformidade
  public/diagramas/            # .drawio (fonte, diagrams.net) + SVG servidos pelo portal
tools/                         # geradores dos diagramas (Python)

Diagramas

Os diagramas estão em docs/public/diagramas/ no formato draw.io (.drawio). Abra em app.diagrams.net (File → Open) ou pela extensão Draw.io Integration no VS Code/Cursor. São gerados por script:

node tools/gerar_drawio.mjs      # arquitetura, fluxo GitOps e esquema do banco
# ou: npm run diagrams

Portal de documentação (VitePress)

Além de ler os .md direto no GitHub/editor, há um portal navegável (menu lateral, busca full-text) gerado com VitePress a partir dos mesmos arquivos de docs/. É opcional — hospedado no GitHub Pages como paliativo até o deploy definitivo via k3s/GitOps (ver ADR-0011).

Pré-requisito: Node.js 20+.

npm install          # instala as dependências (uma vez)
npm run docs:dev     # sobe o portal em modo dev -> http://localhost:5173
npm run docs:build   # gera o site estático em docs/.vitepress/dist
npm run docs:preview # pré-visualiza o build de produção

Os diagramas aparecem como placeholders em ambiente local; no build de publicação (CI) os arquivos .drawio são renderizados em SVG automaticamente.

Contribuindo

Veja CONTRIBUTING.md — convenções de escrita, ADRs e commits.