Finnest Power

Plataforma de Open Banking e Open Insurance do Brasil. 16 modulos distribuiveis, compliance FAPI 1.0 Advanced, venda de codigo-fonte + SaaS.

Open Finance Brasil (BC) Open Insurance (SUSEP) FAPI 1.0 Advanced SaaS + Self-Hosted 8 ADRs

Stack de Tecnologia

Todas as tecnologias sao open source. A stack e unificada para todo o monorepo.

Camada Tecnologia Justificativa
LinguagemTypeScript (Deno)Full-stack, tipagem estatica, ESM nativo
API FrameworkHonoWeb framework leve para Deno/Edge, middleware nativo
MonorepoTurborepo + pnpmBuilds incrementais, cache, workspaces nativos
DatabaseSupabase (PostgreSQL 15)pgmq, pg_cron, Vault, Realtime, Edge Functions
Auth ServerKeycloakUnico OSS certificado FAPI Brasil. PS256, mTLS, DCR
GatewayKongmTLS termination, rate limiting, audit
Frontend AdminVite + React + shadcn/uiSPA estatico, Tailwind CSS, Recharts, TanStack Table
ValidationZod 4SSOT para tipos, validacao e OpenAPI
Error HandlingneverthrowResult pattern — zero throw
LoggingLogTapeStructured logging para Deno
ObservabilidadeOpenTelemetry → GrafanaOTEL Collector vendor-neutral
TestesVitest + Pact + PlaywrightUnit, integration, contract, E2E
CI/CDGitHub ActionsTurborepo Remote Cache, builds seletivos
IaCTerraformSupabase, Cloudflare, Keycloak, GitHub
VersionamentoChangesetsSemver por pacote, CHANGELOG auto-gerado
Pre-commitLefthookdeno-fmt → deno-lint → deno-check → test affected
API DocsScalar (OpenAPI)Portal interativo gerado dos schemas Zod

Arquitetura de Modulos

16 modulos distribuiveis organizados por papel regulatorio x dominio x foco. Cada modulo e um vertical slice autonomo.

Holder Banking — ASPSP (detentora)

D
regulatory-holder-banking-data
Ingestao de dados internos + exposicao FAPI + consent dashboard + metricas
customers accounts credit-cards credit ingestion consent-dashboard
P
regulatory-holder-banking-payments
Processamento de PIX/ITP inbound (ASPSP recebe pagamentos)
pix-processing itp-processing payment-validation

Holder Insurance — ASPSP (detentora)

D
regulatory-holder-insurance-data
Ingestao de dados de seguros + exposicao FAPI + consent dashboard
policyholders policies claims pension ingestion
P
regulatory-holder-insurance-payments
Processamento de premios inbound
premium-processing payment-validation

Receiver / Initiator Banking — TPP / PISP

D
regulatory-receiver-banking-data
DCR + consumo de dados bancarios de IFs externas via FAPI
dcr token-management aggregation
P
regulatory-initiator-banking-payments
Iniciacao de PIX/ITP outbound (PISP)
pix-initiation itp-initiation payment-status

Receiver / Initiator Insurance — TPP / SISS

D
regulatory-receiver-insurance-data
DCR + consumo de dados de seguros de seguradoras externas
dcr token-management aggregation
P
regulatory-initiator-insurance-payments
Iniciacao de pagamentos de premios outbound (SISS)
premium-initiation payment-status

Power Layer API simplificada + add-ons

D
power-receiver-banking-data
Dados normalizados cross-IF, enrichment, categorizacao
connections aggregation institutions
P
power-initiator-banking-payments
Pagamentos simplificados, tracking, webhooks
simplified-payments payment-tracking
D
power-receiver-insurance-data
Dados normalizados cross-seguradora
connections aggregation insurers
P
power-initiator-insurance-payments
Premios simplificados, tracking
simplified-premiums premium-tracking

Admin Analytics transversal

A
power-admin
Consent funnel, connection health, payment metrics, ingestion health, audit log, reports. Frontend Vite + React SPA.
event-consumer capabilities consent-analytics connection-monitoring payment-analytics reporting audit

Shared Incluido em toda venda

C
core
Zero logica de negocio. EventBus, IModuleRegistry, retry, mTLS, PS256, FAPI helpers, logger, OTEL.
$
consent
Gestao de consentimentos (DATA + PAYMENT). Compartilhado entre banking e insurance.
P
data-public
Dados publicos: canais, produtos, participantes do diretorio.

Schemas PostgreSQL

Instancia unica Supabase + schemas declarativos por modulo. DDL em supabase/schemas/, RLS/grants em supabase/migrations/.

infra

audit_log token_cache rate_limits
core

consent

consents consent_resources consent_audit
shared

public_data

channels products participants
shared

regulatory_holder_banking

customers accounts transactions credit_cards credit_card_bills credit_operations received_consents exposure_configs consumption_metrics ingestion_metrics
holder-banking-data + payments

regulatory_holder_insurance

policyholders policies claims premiums pension_plans received_consents exposure_configs consumption_metrics ingestion_metrics
holder-insurance-data + payments

regulatory_receiver_banking

dcr_registrations holder_tokens aggregated_data payment_initiations
receiver-banking + initiator

regulatory_receiver_insurance

dcr_registrations holder_tokens aggregated_insurance premium_initiations
receiver-insurance + initiator

power_receiver_banking

connections accounts transactions credit_cards payments institutions
power-receiver-banking + initiator

power_receiver_insurance

connections policyholders policies claims premiums pension_plans insurers
power-receiver-insurance + initiator

power_admin

events consent_funnel_metrics connection_health payment_metrics ingestion_metrics reports audit_log
admin

Seguranca — FAPI 1.0 Advanced

Fail-closed por padrao. Compliance nao e opcional.

🔒 mTLS + ICP-Brasil

Certificados ICP-Brasil para comunicacao com IFs. Certificados de transporte para DCR.

🔑 PS256 (RS256 rejeitado)

Tokens assinados com PS256. Qualquer token RS256 e rejeitado automaticamente.

🛡 FAPI Headers

x-fapi-interaction-id, x-fapi-auth-date, x-fapi-customer-ip-address obrigatorios.

🔐 RLS + Encryption

Row Level Security em todas as tabelas de usuario. CPF, CNPJ, PIX keys encriptados com pgcrypto.

⚠ Zero PII em Logs

CPF, CNPJ, tokens, senhas, chaves PIX, numeros de conta nunca sao logados.

🛠 PAR + PKCE + DCR

Pushed Authorization Request com PKCE para consent. Dynamic Client Registration com certificado.

Middleware Stack (ordem obrigatoria)

requestId()rastreamento
→
timing()performance
→
secureHeaders()OWASP
→
cors()allowlist
→
requestLogger()LogTape
→
errorHandlerResult
→
requireAuthJWT / mTLS

Regras Nao-Negociaveis

Violacoes bloqueiam merge. Sem excecoes.

✗
No throw — usar Result pattern (neverthrow): ok() / err()
✗
No console.log — usar LogTape structured logging
✗
No any — usar unknown + validacao Zod
✗
No @ts-ignore — corrigir o tipo
✗
No non-null assertion ! — usar ?. + ??
✗
No cross-module imports — usar IEventBus para comunicacao
✗
No SQL em services — acesso via repositories apenas
✗
No type assertions — usar Zod parseJsonBody() retornando Result
✗
No PII em logs — CPF, CNPJ, PIX keys, tokens proibidos
✗
No hardcoded secrets — env vars apenas
✗
No --no-verify — corrigir o problema, nao bypassar hooks
✗
No tipos manuais — z.infer<typeof Schema> apenas

Limites de Tamanho (BLOCKING)

ElementoMax Linhas
Funcao / metodo25
Route handler15
Service class300
Repository class200
Arquivo400
Schema file300
Complexidade ciclomatica / fn5
Nesting depth2
Parametros / fn3

Estrategia de Testes

Piramide de 4 niveis. 100% dos testes sao entregues junto ao produto.

Unit Tests

Vitest

Logica isolada, sem I/O. Co-localizados com source. *.test.ts

Integration

Vitest + Supabase local

Banco real. Apenas cenarios nao cobertos por unit (upsert, pgmq, pg_cron). *.integration.test.ts

Contract

Pact (consumer-driven)

Contratos com APIs das IFs + schema validation Zod para APIs proprias.

E2E / Smoke

Playwright

Smoke tests do dashboard admin e fluxos criticos. Apenas happy path.

Coverage Thresholds

ModuloBranchLine
core90%95%
regulatory-*85%90%
power-*80%85%

CI/CD Pipeline

GitHub Actions + Turborepo + Supabase Preview Branches. Trunk-based development.

PR Pipeline (CI)

Lintdeno fmt + lint
⇄
Typecheckdeno check
⇄
Unit Testsvitest
⇄
Changesetcheck
→
Preview BranchSupabase auto
→
IntegrationDB real
→
ContractPact

Deploy Pipeline (CD)

Merge to main
→
supabase db pushmigrations
→
functions deployEdge Functions
⇄
Cloudflare Pagesadmin SPA
→
Smoke Testshealth checks
→
Release Tagchangeset

Ambientes

Local

supabase start
Docker local (~7 containers)

Preview

Supabase Preview Branch
Automatico por PR

Staging

Supabase Cloud separado
Validacao pre-prod

Production

Supabase Cloud + Cloudflare
Deploy automatico

Infrastructure as Code

Supabase

Projetos, secrets, configuracao de Edge Functions

Cloudflare

Pages, DNS, dominios customizados, WAF

Keycloak

Realm FAPI, clients, roles, identity providers

GitHub

Branch protection, secrets, environments

Grafana

Data sources, dashboards, alert rules

Terraform

Modulos reutilizaveis por ambiente (staging/prod). State remoto.

Fluxos de Dados

Dois fluxos principais: Receiver (agrega dados de IFs externas) e Holder (ingesta dados internos).

Fluxo Receiver (agregacao cross-IF)

1. Cliente chama: POST /power/v1/connections { institutionId }

2. power-receiver-banking-data → chama IDCRManager.register()
   do regulatory-receiver-banking-data (in-process, zero latencia)

3. regulatory faz DCR na IF via FAPI (mTLS, PS256)
   persiste no schema regulatory_receiver_banking

4. power normaliza o resultado, cria Connection
   no schema power_receiver_banking

5. power inicia sync: chama IDataFetcher.fetchAccounts()

6. regulatory busca dados raw da IF via FAPI

7. power normaliza → grava em power_receiver_banking
   (formato unificado, independente da IF)

8. Cliente consulta: GET /power/v1/accounts
   (dados normalizados, paginacao consistente)

Fluxo Holder (ingestao + exposicao)

1. Sistema interno chama: POST /holder/v1/ingestion/customers
   (Keycloak Bearer token, sem FAPI)

2. regulatory-holder-banking-data valida payload (Zod)
   normaliza dados, persiste no schema regulatory_holder_banking

3. Emite evento: ingestion.completed
   (consumido por power-admin para metricas)

4. IF Receiver chama: GET /open-banking/v1/customers
   (API regulatoria, FAPI mTLS + PS256)

5. regulatory valida consent, aplica RLS
   le dados do mesmo schema regulatory_holder_banking

6. Formata conforme spec oficial e responde a IF Receiver

Fluxo Admin (eventos)

Todos os modulos emitem eventos tipados via IEventBus (core)
  ↓
consent.created | connection.synced | payment.completed | ingestion.completed
  ↓
power-admin consome eventos, persiste em power_admin.events (append-only)
  ↓
pg_cron jobs computam metricas incrementais (hourly, 5min, daily)
  ↓
Dashboard SPA (Vite + React) le via API → Consent Funnel, Connection Health, etc.

Regras de Dependencia

Imports cross-module sao BLOQUEADOS. Comunicacao cross-module via IEventBus.

PERMITIDO
  ./                                 → imports locais ao modulo
  @finnest/core                      → infraestrutura (EventBus, retry, mTLS)
  @finnest/{mesmo-dominio-data}       → intra-dominio: payments → data (unidirecional)

BLOQUEADO
  @finnest/{outro-modulo}/            → cross-module NUNCA
  banking ↔ insurance              → cross-dominio NUNCA
  holder ↔ receiver               → cross-role NUNCA
  power → regulatory (tabelas)    → "codigo sim, banco nao"

CORE
  Entra no core SOMENTE se:
  (a) e infraestrutura E (b) usado por 3+ modulos E (c) zero logica de negocio
  ~3.000 linhas maximo

Architecture Decision Records

8 ADRs definem toda a arquitetura. Conflitos entre constituicao e ADR sao resolvidos atualizando ambos.

ADR-001 Monorepo Foundation

Turborepo + pnpm workspaces. Venda modular nativa via script de empacotamento. 16 modulos em modules/. Deploy por namespace K8s.

ADR-002 Supabase Declarative Schemas

Instancia unica + schemas declarativos por modulo. DDL como source of truth. RLS/grants em migrations manuais. Seed modular.

ADR-003 Power Layer Receiver

Modulos power in-process com schemas proprios. API simplificada (Bearer token, paginacao, webhooks). Enrichment e normalizacao cross-IF.

ADR-004 Holder Layer — Ingestao + FAPI Unificados

Holders separados em -data e -payments por dominio. Ingestao absorvida no regulatory. Duas areas de rotas: interna (Keycloak) e FAPI (mTLS).

ADR-005 Power Layer Admin

Modulo transversal baseado em eventos. Consent funnel, connection health, payment metrics, ingestion health, audit. Frontend Vite + React SPA.

ADR-006 Testing Strategy

Piramide de 4 niveis: Unit (Vitest) → Integration (DB real) → Contract (Pact) → E2E (Playwright). 100% dos testes entregues ao cliente.

ADR-007 Technical Standards

9 dimensoes: vertical slice, error handling, Zod SSOT, seguranca, code quality, database, git, quality gates, OpenAPI pipeline.

ADR-008 CI/CD & Infra

GitHub Actions + Turborepo + Supabase Preview Branches. Deploy SaaS em Supabase Cloud + Cloudflare Pages. Terraform para IaC. Changesets para versionamento.

Modelo de Venda

Codigo-fonte (R$80-100k) + SaaS. Modulos power sao add-ons (+40-50%). Empacotamento via script.

Holder Packages

  • Banking Data — regulatory-holder-banking-data + consent + data-public + core
  • Banking Payments — regulatory-holder-banking-payments + consent + core
  • Banking Full — data + payments + consent + data-public + core
  • Insurance Data — regulatory-holder-insurance-data + consent + data-public + core
  • Insurance Payments — regulatory-holder-insurance-payments + consent + core
  • Insurance Full — data + payments + consent + data-public + core

Sem add-ons Power para holders — tudo incluido.

Receiver / Initiator Packages

  • Banking Data (base) — regulatory-receiver-banking-data + consent + core
  • Banking Data + Power — + power-receiver-banking-data + power-admin
  • Initiator Payments (base) — regulatory-initiator-banking-payments + consent + core
  • Initiator Payments + Power — + power-initiator-banking-payments + power-admin
  • Insurance Data (base) — regulatory-receiver-insurance-data + consent + core
  • Insurance Data + Power — + power-receiver-insurance-data + power-admin

Power modules sao add-ons (+40-50% de ticket).

Bundles

  • Full Banking + Power — todos os modulos banking + power-admin
  • Full Insurance + Power — todos os modulos insurance + power-admin
  • SaaS (tudo) — todos os 16 modulos (subscription)

Entrega Self-Hosted

  • Acesso ao repositorio Git ou tarball de release
  • Modulos comprados + core + shared + schemas filtrados
  • 100% dos testes incluidos
  • ADRs + docs de setup, deploy, testing, customization
  • Terraform modules para provisionar infra
  • openapi-power.json para documentacao de API