core/billing-finance-core/docs/architecture.md

Arquitetura do billing-finance-core

Visão geral

O serviço billing-finance-core é responsável pelo core financeiro, billing, fiscal e CRM da plataforma SaaS multi-tenant. Ele confia no identity-gateway para autenticação e recebe o tenantId via JWT interno.

Principais componentes

• Core: Guard de autenticação JWT e contexto de tenant.
• Módulos de domínio: tenants, planos, assinaturas, invoices, payments, fiscal e CRM.
• Gateways de pagamento: padrão Strategy para Pix, boleto e cartão.
• Persistência: PostgreSQL com Prisma e migrations.

Multi-tenant

• Todas as rotas usam tenantId extraído do JWT interno.
• Consultas sempre filtram por tenantId.

Integrações

• Identity Gateway: JWT interno contendo tenantId, userId, roles.
• Gateways de pagamento: integração via webhooks e reconciliação idempotente.