Kabrun
Plataforma global para venda de produtos digitais, cursos, comunidades, assinaturas e mentorias.
A Kabrun recebe o pagamento do comprador, registra a venda no seu próprio ledger, cobra a taxa da
plataforma e repassa o saldo ao produtor quando o prazo de liberação vence. Ou seja: é uma
plataforma de pagamentos/marketplace, não uma loja com checkout integrado.
Mercados da Fase 1: Brasil, União Europeia e Estados Unidos (BRL, EUR, USD).
Índice
Arquitetura
Cada camada tem uma responsabilidade única, e elas nunca se misturam:
| Camada | Responsabilidade |
|---|
| Keycloak | Identidade: login, senha, recuperação, verificação de e-mail, sessão, MFA |
| Kabrun | Autorização: quem pertence a qual organização e o que pode fazer |
| PostgreSQL | Fonte de verdade de commerce e finanças |
| MongoDB | Dados flexíveis: apresentação do checkout, eventos, payloads |
| Redis | Cache, locks, rate limit e (futuramente) filas |
| Payment provider | Movimentação real do dinheiro (Stripe) |
| Ledger | Fonte de verdade financeira da Kabrun |
| Balance | Projeção do ledger (cache), nunca fonte de verdade |
| Order | Intenção comercial |
| Payment | Movimentação vinda do comprador |
| Payout | Movimentação indo para o produtor |
O fluxo de uma requisição:
Server Component / Server Action / Route Handler
↓ (Zod valida a entrada, requireUser/requireOrganization autoriza)
Service ← regra de negócio, um domínio por service
↓
Repository ← interface; a implementação Prisma/Mongo fica isolada
↓
PostgreSQL / MongoDB ← operações financeiras sempre em transação
Serviços nunca importam PrismaClient, MongoClient ou o SDK da Stripe. Eles recebem
repositories e interfaces de provider (inversão de dependência), o que também torna os testes
determinísticos. A montagem fica em src/server/services.ts e
src/server/container.ts.
Stack
- Next.js 16 (App Router, Server Components, Server Actions) + React 19 + TypeScript strict
- Tailwind CSS 4 + shadcn/ui + Lucide
- Zod para validação e React Hook Form/forms nativos progressivos
- Keycloak (OIDC Authorization Code + PKCE, implementado à mão com
jose)
- PostgreSQL 17 + Prisma 7 (driver adapter
@prisma/adapter-pg)
- MongoDB 8 para documentos e eventos
- Redis 7 para cache, locks e rate limit
- Stripe (Payments, Connect, Billing, Webhooks) — com
MockPaymentProvider para desenvolvimento
- Vitest para testes (unitários + integração contra Postgres real)
- Docker Compose para a infraestrutura local
PostgreSQL vs MongoDB
PostgreSQL é a fonte de verdade de tudo que é relacional e financeiro:
User, Organization, OrganizationMember, Product, Offer, Checkout, Customer, Order,
OrderItem, Payment, Transaction, Subscription, Refund, Dispute, LedgerJournal,
LedgerEntry, Balance, Reserve, Payout, PayoutDestination, MerchantAccount,
SettlementPolicy, PlatformFeePolicy, Affiliate, Coupon, Course, Enrollment,
ApiKey, AuditLog, WebhookEvent, OutboxEvent, IdempotencyKey.
MongoDB guarda o que é flexível, volumoso ou muda de forma com frequência:
checkout_configs (versionado), analytics_events, webhook_payloads, provider_snapshots,
activity_events, risk_events.
Regra que não se quebra: dado financeiro nunca tem o MongoDB como única fonte de verdade.
O preço oficial vem sempre da Offer no PostgreSQL; o Mongo só configura a apresentação.
Identidade (Keycloak)
Realm kabrun, client kabrun-web (confidencial, PKCE S256). A Kabrun não armazena senhas:
a tabela User guarda keycloakUserId (único), e-mail, nome e preferências.
GET /api/auth/login inicia o fluxo (state + nonce + PKCE em cookie assinado de 10 min)GET /api/auth/callback valida state/nonce, troca o code, verifica o ID token via JWKS e cria a sessãoPOST /api/auth/logout limpa a sessão e encerra a sessão no Keycloak (RP-initiated logout)
A sessão é um JWT HS256 em cookie httpOnly, SameSite=Lax (e Secure em produção).
O src/proxy.ts faz apenas a checagem otimista (existe sessão válida?);
a autorização real acontece no servidor, em cada página e action.
Multi-tenancy e autorização
Toda entidade de negócio carrega organizationId, e todo repositório filtra por ele.
Helpers: getCurrentUser(), requireUser(), requireOrganization(), requireRole(),
requirePermission(). O organizationId que chega do cliente (cookie, formulário, URL) nunca é
confiado: o vínculo é sempre reconferido no banco.
Papéis: OWNER, ADMIN, FINANCE, SUPPORT, MARKETING, VIEWER (mapeados para permissões em
permissions.ts), mais o papel global PLATFORM_ADMIN
para a equipe Kabrun (/admin).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
