Arquitetura
Monorepo TypeScript com responsabilidades explícitas e serviços implantáveis separadamente.
Componentes
| Caminho | Responsabilidade |
|---|---|
apps/web | Next.js, React, site público, conta, painel, docs PT/EN e checkout |
apps/api | Fastify, identidade, autorização e regras de negócio |
packages/core | Schemas Zod, catálogo e política compartilhada |
packages/database | Prisma, modelos e migrações PostgreSQL |
packages/sdk | Cliente servidor e montagem de iframe |
apps/api/src/worker.ts | Processamento durável de webhooks, notificações e e-mail |
O web encaminha /v1/* e /api/auth/* à API interna. A API concentra autoridade e persistência. O worker compartilha os eventos do PostgreSQL e não depende de memória de um processo web.
Decisões
Next.js atende site público, conta, painel, documentação e checkout. Fastify mantém a API independente da renderização. Prisma oferece migrações versionadas e tipos. PostgreSQL concentra dados e fila inicial, evitando exigir Redis nesta fase.
A fila usa FOR UPDATE SKIP LOCKED e leases, permitindo múltiplos workers. Chaves únicas protegem idempotência entre instâncias. Cotações usam cache local curto; não são saldo ou autoridade de liquidação.
Negócios e operadora
Cada conta possui um negócio. IDs de workspace continuam delimitando recursos, sem oferecer um seletor de múltiplos negócios por conta. O estabelecimento cadastra endereços fixos por rede e ativo nas configurações autenticadas. O checkout nunca aceita um beneficiário escolhido pelo pagador.
O operador do Magnum gerencia uma credencial global privada da 4P no backend. Chaves Magnum são credenciais separadas, limitadas ao negócio. Essa organização técnica não comprova autorização da 4P para uma plataforma ou múltiplos estabelecimentos sob uma conta; o processamento real permanece bloqueado até aprovação expressa.
Limites da entrega
Não existe ledger de saldo disponível, custódia de chaves, liquidação comercial live ou faturamento. Esses módulos não podem ser simulados por uma soma de pagamentos. O sistema está preparado para evolução, sem alegar que o produto financeiro já está homologado.