Pular para o conteúdo principal

DOCS-ADR-001 — Arquitetura do Portal de Documentação

CampoValor
StatusAceita
Data2026-06-17
DecisoresArquitetura / Plataforma FinWAY
EscopoDocumentação técnica da plataforma FinWAY
Relacionada aDOCS-ADR-002, Blueprint

Contexto​

A documentação da FinWAY hoje vive em finway-api-guides, um portal Scalar que combina guias de jornada (Markdown) com a referência da API (finway.json, OpenAPI 3.0.3). O modelo atende bem a referência de API, mas não cobre a camada conceitual (arquitetura, domínio, operação, compliance) nem escala para um produto multi-serviço/multi-repo. O conhecimento fica fragmentado e há risco de divergência entre documentação e código.

É necessário evoluir para um portal técnico completo, padronizado e auditável, alinhado ao padrão já consolidado no FinPSTI Docs.

Decisão​

O FinWAY Docs será um portal central de documentação baseado em Docs-as-Code, construído com Docusaurus v3.

Concretamente:

  1. Documentação como código: Markdown/MDX versionado em Git, revisado por Pull Request e publicado por automação.
  2. Migração in-place no repositório finway-api-guides, preservando finway.json, os guias e o histórico.
  3. Docusaurus v3 (TypeScript) como gerador, com Mermaid e busca local habilitados, routeBasePath: '/' e blog desabilitado.
  4. Arquitetura de informação em seções fixas: Arquitetura · Domínio · Jornadas · Dados & APIs · Operação · Compliance.
  5. Ownership distribuído: cada time documenta seu domínio; o portal central cura e mantém o padrão.

Esta ADR fixa o modelo. A Fase 1 cria apenas o andaime; migração de guias, API Reference e demais conteúdos ocorrem em fases posteriores.

Consequências​

Positivas​

  • Portal técnico completo (não só referência de API) e ponto único de descoberta.
  • Padronização via templates; base pronta para geração de contratos (DOCS-ADR-002).
  • Documentação versionada e auditável — adequado a um produto financeiro.
  • Aderência ao padrão FinPSTI Docs.

Negativas / Custos​

  • Esforço de migração e curva de aprendizado do time.
  • Diretivas Scalar e nomes com acento exigem conversão.
  • Exige disciplina cultural (documentar no fluxo de PR).

Neutras​

  • O conteúdo legado (scalar.config.json e documentation/) já foi removido na fase de limpeza — o histórico permanece no Git.
  • Dependência do ecossistema Docusaurus (reversível — conteúdo é Markdown portável).

Alternativas consideradas​

AlternativaPor que foi descartada
Manter Scalar puroNão cobre a camada conceitual nem escala para multi-repo.
Wiki (Confluence/Notion)Fraco em versionamento/auditoria; desacoplado do Git; propenso a drift.
Só READMEs por repoSem visão unificada nem navegação cruzada.
Outro gerador (MkDocs, Backstage TechDocs)Viável; Docusaurus preferido por MDX/React, Mermaid nativo, busca, versionamento e alinhamento ao FinPSTI.