FinWAY Docs — Blueprint de Migração

Consolida o plano aprovado para evoluir o repositório finway-api-guides (API Guides em Scalar) para o portal técnico completo FinWAY Docs em Docusaurus, no padrão arquitetural do FinPSTI Docs. Decisões formais: DOCS-ADR-001 e DOCS-ADR-002.

Inventário atual

Repositório: github.com/buildersbank/finway-api-guides · domínio Scalar: finway.docs.finaya.tech.

Artefato	Descrição
`finway.json` (416 KB)	OpenAPI 3.0.3 — `Finway API v2.0.0`. 113 paths · 136 operações (POST 79, GET 32, DELETE 13, PATCH 7, PUT 5) · 22 tags · 200 schemas · security `x-buildersbank-authorization` + `client_id`.
`scalar.config.json`	Configuração do Scalar: navegação, tema `finaya`, custom domain, mapa de páginas.
`documentation/*.md` (12 arquivos, ~119 KB)	Guias de jornada: Onboarding, PIX, Accounts, Autenticação, Alteração de Senha/PIN, Saldo e Extrato, Crédito, QR Code Dinâmico, Resposta de Infração, Webhooks + Introdução.

Domínios (tags) no OpenAPI: MED (16), Accounts (12), Onboarding PF (10), Onboarding PJ (9), Pix Keys (9), Dynamic QR Code (8), Devices Management (7), Pix Transfer (7), Password Recovery (6), Pix Limits (6), Pix Automatic (6), Webhooks (6), Change Password (5), Change Pin (5), Credentials Management (5), Authentication (4), Pix Claims (4), Dynamic QR Code Webhooks (4), Transactions (3), Notifications (2), OAuth Token (1), Storage Files (1).

Observações materiais:

Zero diagramas Mermaid nos guias atuais (oportunidade de enriquecimento).
Nomes de arquivo com acentos (ex.: jornada-alteração-de-senha.md) → exigem slugs ASCII.
introduction.md usa diretivas proprietárias Scalar (:::scalar-card, ::::scalar-row) que não renderizam em Docusaurus.
Webhooks documentados em Markdown manual (o OpenAPI é 3.0.3, sem objeto webhooks 3.1).

O que preservar

finway.json integralmente (fonte da API Reference — não editar à mão).
Os 12 guias de jornada (conteúdo).
finaya-webhooks.md (base da seção Eventos).
Taxonomia de domínios (tags) como espinha da arquitetura de informação.
Identidade finaya e domínio.
Histórico Git (migração in-place).

O que migrar

De	Para	Transformação
`documentation/*.md`	`docs/jornadas/*.md`	front-matter, slugs ASCII, correção de links
`introduction.md` (Scalar)	`src/pages/index.tsx`	converter `:::scalar-card` em cards Docusaurus
Navegação `scalar.config.json`	`sidebars.ts`	mapeamento 1:1
`finway.json` no viewer Scalar	API Reference embutida (`/api`)	`@scalar/docusaurus` (runtime, sem geração)
`finaya-webhooks.md`	`docs/dados/eventos/`	migrar; depois AsyncAPI

O que criar novo

Andaime Docusaurus (feito na Fase 1): package.json, docusaurus.config.ts, sidebars.ts, homepage, CSS, assets.
Seções conceituais: Arquitetura, Domínio, Operação, Compliance.
Homepage padrão FinPSTI (hero + contadores + cards + acesso rápido + badges).
Diagramas Mermaid de sequência para jornadas.
Busca local; pipeline CI/CD (fase posterior).

Estrutura final (alvo)

finway-api-guides/                 (repo vira o portal FinWAY Docs)
├── docusaurus.config.ts · sidebars.ts · package.json · tsconfig.json
├── static/finway.json             (PRESERVADO — fonte única, servida em /finway.json)
├── templates/                     (templates reutilizáveis — FORA de docs/, não publicados)
├── docs/
│   ├── architecture/              (governança: blueprint + ADRs)
│   └── arquitetura/ · dominio/ · jornadas/ · dados/ · operacao/ · compliance/
├── src/pages/index.tsx · src/pages/index.module.css · src/css/custom.css
└── static/img/

Estratégia OpenAPI

A API Reference é renderizada em runtime pelo @scalar/docusaurus em /api, a partir de static/finway.json (servida em /finway.json) — embutida no portal Docusaurus, sem geração de páginas. O contrato não se edita no portal: correções vão ao finway.json na origem.

Decisão substituída: chegou-se a gerar a API Reference como MDX estático via docusaurus-plugin-openapi-docs + docusaurus-theme-openapi-docs. A abordagem foi revertida (patch de webpack frágil e ~514 arquivos gerados versionados) em favor do Scalar em runtime, que ainda traz cliente de testes interativo. Detalhes e racional na DOCS-ADR-002 — Atualização 2026-06-19.

Estratégia Webhooks / Eventos

Curto prazo: migrar finaya-webhooks.md para docs/dados/eventos/ como Markdown. Médio prazo: descrever os eventos em AsyncAPI por serviço e gerar as páginas (DOCS-ADR-002).

Estratégia multi-repo

Portal central (finway-docs) agrega: conteúdo conceitual escrito à mão + contratos gerados dos repositórios dos microsserviços (OpenAPI, AsyncAPI, schema de dados). Ownership distribuído por time/repo; o portal cura e padroniza. A mecânica de sincronização será definida em fase posterior.

Fases de migração

Fase	Escopo	Status
1	Andaime Docusaurus (este commit)	Concluída
2	Migrar os 12 guias para `docs/jornadas/`	Pendente
3	API Reference de `finway.json` (Scalar embutido em `/api`)	Pendente
4	Camada conceitual (Arquitetura/Domínio/Compliance/Operação) + Mermaid	Pendente
5	Eventos/Webhooks (Markdown → AsyncAPI)	Pendente
6	Busca, CI/CD, publicação, redirects	Pendente
7	Limpeza (`documentation/`, `scalar.config.json`)	Concluída (legado removido; histórico no Git)

Riscos

Diretivas Scalar não renderizam em Docusaurus → conversão manual.
Nomes com acento → slugs ASCII + redirects.
Quebra de links na transição → plugin-client-redirects + checagem de links no build.
Divergência de UX (Scalar vs gerador nativo) → opção de ponte.
finway.json só com server -dev → adicionar sandbox/prod antes de publicar.

Inventário atual​

O que preservar​

O que migrar​

O que criar novo​

Estrutura final (alvo)​

Estratégia OpenAPI​

Estratégia Webhooks / Eventos​

Estratégia multi-repo​

Fases de migração​

Riscos​

Checklist (Fase 1)​