Princípios Arquiteturais

Princípios que orientam a documentação e a evolução do portal FinWAY Docs. Os itens marcados com [FATO] já se refletem na estrutura atual do repositório; [INFERÊNCIA]/[TODO] indicam direção acordada porém ainda não implementada.

1. API-first

A plataforma é exposta como uma API unificada descrita em OpenAPI (finway.json, Finway API v2.0.0) [FATO]. O contrato da API é o ponto de partida da integração e da documentação.

2. Docs-as-Code

A documentação vive em Git, em Markdown/MDX, é revisada por Pull Request e publicada por build (Docusaurus) [FATO]. Ver Blueprint e DOCS-ADR-001.

3. Contrato OpenAPI como fonte de verdade

A API Reference é renderizada em runtime pelo Scalar (@scalar/docusaurus) a partir do finway.json — não é escrita à mão nem gerada como páginas MDX [FATO]. A fonte única da verdade é static/finway.json (servida em /finway.json); correções vão ao OpenAPI na origem, e a validação é feita por Spectral (validate:openapi). Ver DOCS-ADR-002.

4. Jornadas documentadas manualmente

Os fluxos de negócio são escritos à mão em Jornadas, pois exigem narrativa e contexto que o contrato não captura [FATO].

5. Segurança por token/header

O acesso à API é autenticado por headers (client_id + token JWT em x-buildersbank-authorization) [FATO — securitySchemes]. Detalhes em Segurança.

6. Rastreabilidade entre jornadas e API Reference

Cada jornada deve referenciar os endpoints correspondentes na API Reference, e vice-versa, para manter navegação cruzada [INFERÊNCIA — prática-alvo]. Cobertura completa de links: [TODO].

7. Versionamento futuro

A Finway API já carrega versão (v2.0.0) [FATO]. O versionamento da documentação (snapshots por release) ainda não está configurado [TODO] — planejado para fase posterior.