docs/ — Source of Truth
docs/ — Source of Truth
Diretório canônico de toda decisão arquitetural, fluxo, estudo e operação do ZapNotei.
Regra: decisão consequente → ADR novo (NUNCA editar existente). Mudou stack/fase/schema → atualizar fragmento correspondente +
ultima_atualizacaono frontmatter.
Mapa de navegação
| Pasta / Arquivo | Conteúdo | Quando consultar |
|---|---|---|
adr/ | 44 ADRs (Accepted) + template + README índice | Antes de TODA decisão técnica consequente |
arquitetura/ | 11 fragmentos (00-10) + dominio-mapeamento + dominio-migracao + setup-aws-kms + principios-hexagonal-tokenizacao | Antes de tocar stack, infra, hexagonal |
flowmaps/ | 21 flowmaps numerados + wireframes/ (63 surfaces) + wireframes/prototypes/ (HTML navegáveis) + sessoes-chat/ | Antes de codar UI, flow conversacional, ou rota Next.js |
studies/ | 27 studies de libs/serviços (1 por dependência da stack) | Antes de implementar lib/SDK/API |
runbooks/ | 15 runbooks (setup vendors + incident response + LGPD + restore + Vercel env real values) | Em incidente operacional ou setup novo |
implementation-plan/ | 1 plano executável (F1.0a auth+onboarding); cresce conforme sub-fases destravam | Antes de codar features de uma sub-fase com ≥10 tasks dependentes |
telemetry/ | events catalog (~125) + implementation-spec + governance | Antes de emitir evento novo |
prd/ | 9 arquivos PRD v4.1 (executive summary → DoD) | Para escopo de produto / aprovação |
brand-voice/ | 9 docs (princípios → microcopy → checklist) | Antes de escrever copy user-facing |
eval/ | Eval set methodology (gates F1.2a NFS-e ≥95% / F1.2b NF-e ≥90%) | Antes de tocar prompt LLM ou modelo |
audits/ | Audits pós-implementação | Pós-marco arquitetural |
Arquivos raiz docs/
| Arquivo | Tópico |
|---|---|
plano-fases.md | Cronograma 5 fases + sub-fases F1 (F0/F1.0/F1.1/F1.2a/F1.2b/F2/F3/F4/F5) |
schema-db.md | Modelo de dados Postgres + RLS multi-tenant 3 níveis (account → companies → memberships) |
clientes-crm.md | CRM PJ+PF (apelido + auto_save + painel UI + LGPD) — ADR-0013 + ADR-0035 |
error-taxonomy.md | Códigos Focus + LLM + auth + crypto + business → severity → recovery → mensagem PT-BR |
session-lifecycle.md | Tipos sessão, TTL, drafts, transferência intencional, recovery |
conversational-philosophy.md | 9 princípios bot adaptativo + anti-engessamento + táticas |
Bidirecionalidade
Mudança consequente em qualquer doc obriga atualização cruzada. Padrão:
| Mudou em | Atualizar |
|---|---|
adr/NNNN-*.md (NOVO) | adr/README.md índice + arquivos consumidos pelo ADR |
arquitetura/0X-*.md | ultima_atualizacao no frontmatter + ADR se decisão mudou |
schema-db.md | Migrations correspondentes + ADRs que tocam o schema + flowmaps consumidores |
flowmaps/NN-*.md | Wireframes correspondentes + protótipos navegáveis afetados |
studies/<lib>-study.md | Adapter em app/src/adapters/<categoria>/ quando lib for implementada |
telemetry/events.md | Schema Zod em app/src/core/telemetry/events.ts (lint CI bloqueia drift) |
runbooks/<incident>.md | Disciplina ADR-0008 (runbooks como source of truth executável) |
plano-fases.md | CLAUDE.md bootstrap state se cronograma mudou |
Política inegociável
- NUNCA editar ADR existente — supersede via ADR novo. Path
web/...em ADR ≤ 0042 lê-se comoapp/...(interpretation layer ADR-0047) - NUNCA commit
.envou secrets em claro - NUNCA
console.logde PII (CPF/CNPJ/A1/senhas/OTP) — usarapp/src/core/redact/pii.ts - Antes de tocar fluxo conversacional: ler flowmap correspondente. Antes de tocar lib: ler study. Antes de tocar ADR: criar novo.
Não consultar
app/para decisões — código é consequência, não fonte da verdadedesign-system/para regras de produto — só visual_local-context/para arquitetura — é contexto operacional do dev, não doc canônica
Ver também
../CLAUDE.md— agentic rules + stack + workflow../README.md— overview do projeto../app/README.md— setup local + estrutura de código../content/README.md— assets editoriais (imagens IA/manual + transcripts vídeo + futuros áudios)../infra/README.md— deployment artifacts (CF Pages, Workers, VPS)