Arquitetura do COBRES
O COBRES é uma plataforma SaaS compartilhada. Uma API e um banco atendem várias organizações; cada cliente é uma organização desse ambiente. A separação de dados acontece pelo contexto da requisição, pelas políticas do PostgreSQL e pelas regras de escopo do produto.
Componentes
| Componente | Responsabilidade |
|---|---|
| API FastAPI | Autenticar, validar contratos, verificar permissões e executar operações SQL |
| PostgreSQL | Persistir dados, isolar organizações com RLS e executar funções de domínio |
| Redis | Limites de frequência, tickets e coordenação de tarefas |
| Worker | Consumir outbox e processar e-mails, webhooks e trabalhos registrados |
| Armazenamento de objetos | Guardar arquivos acessados por URLs assinadas |
| Console | Administração da plataforma pela equipe autorizada |
| Backoffice | Operação de cobrança e administração da organização |
| Portal | Acesso do público externo: o portal do credor |
Três planos de acesso
As interfaces de equipe usam /api/v1/*. A sessão informa se o ator está no plano platform ou organization. Integrações usam a mesma família de rotas com uma chave vinculada à organização. O portal usa /api/audience/v1/*, com identidade, sessões e pool de banco próprios.
Uma Identity representa uma pessoa da equipe. Sua associação a uma organização é uma membership. Um EndUser representa uma pessoa do portal, vinculada às organizações por relationships. Um token de um plano não abre o outro.
Caminho de uma operação
- O middleware estabelece o identificador da requisição e autentica o ator.
- A dependência abre uma transação no pool correto e estabelece o contexto SQL.
- A rota verifica a permissão e as regras específicas de escopo.
- A escrita chama a função SQL responsável pela mudança.
- A transação confirma antes de a resposta sair.
- Trabalhos assíncronos seguem pela outbox quando previstos pelo módulo.
Os módulos do COBRES são registrados no manifesto de produto. A arquitetura preserva a fronteira entre a camada de plataforma (identidade, arquivos e auditoria) e os módulos de devedores, dívidas, negociação e financeiro.
Onde confirmar o contrato
No repositório, comece por api/app/main.py, api/app/core/database.py, api/app/product/manifest.py e api/app/sql/. Os contratos detalhados ficam em application/PRD.md e nos PRDs de cada superfície.
Leia também isolamento entre organizações e extensões do produto.