Entrypoints¶
O Spryx Backend expõe sua funcionalidade através de 3 entrypoints ativos e 1 planejado, cada um servindo um público diferente com requisitos de autenticação distintos.
Visão Geral¶
| Entrypoint | Público | Auth | Status |
|---|---|---|---|
| App API | Tenants (usuários do app) | JWT · scope tenant:* + X-Tenant-Id |
✅ Ativo |
| Backoffice API | Staff interno | JWT · scope bo:* |
✅ Ativo |
| Celery Worker | Interno (async) | Redis broker | ✅ Ativo |
| Public API | Desenvolvedores externos | API Key | ⏳ Planejado |
App API¶
A API principal voltada ao usuário, consumida pelo frontend da plataforma Spryx.
Entrada: src/entrypoints/http/app/main.py
Imagem: docker/Dockerfile.app
Categorias de rotas¶
| Prefixo | Propósito | Auth necessária |
|---|---|---|
/v1/tenant/* |
Todas as operações do tenant (agentes, contatos, billing…) | JWT + header X-Tenant-Id |
/v1/core/* |
Auth de usuário, perfil, gerenciamento de sessão | JWT |
/v1/public/* |
Webhooks de entrada (Stripe, WhatsApp, Google Drive) | Nenhuma |
/v1/catalog/* |
Configuração de produto/menu (somente leitura) | Nenhuma |
Todas as rotas de tenant impõem isolamento multi-tenant — cada requisição é escopada ao tenant identificado no header X-Tenant-Id, validado contra os claims do JWT.
Funcionalidades em tempo real (streaming de agentes, notificações ao vivo) são servidas via WebSocket em /v1/tenant/websocket/.
Backoffice API¶
API de administração interna usada pelo time Spryx para operações da plataforma.
Entrada: src/entrypoints/http/backoffice/main.py
Imagem: docker/Dockerfile.backoffice
O que gerencia¶
- Ciclo de vida dos tenants (criar, configurar, suspender)
- Billing: planos, entitlements, acompanhamento de assinaturas
- Gestão de usuários e staff, templates de papéis
- Log de auditoria da plataforma
- Impersonação de staff (para suporte)
- Itens de menu e configuração de catálogo
Todas as rotas requerem tokens JWT com scope bo:*. Usuários staff operam em todos os tenants sem restrições de isolamento.
Celery Worker¶
Processador de tarefas assíncronas em background. Roda separadamente da API, mas compartilha o mesmo codebase e banco de dados.
Entrada: src/entrypoints/worker/app.py
Imagem: docker/Dockerfile.worker
Broker/Backend: Redis
Filas¶
| Fila | Responsabilidades |
|---|---|
default |
Memória de IA, sync do Google Drive, refresh de tokens OAuth, limpeza de auditoria |
indexing |
Pipeline RAG: parse de documento → chunking → embedding |
As tasks sempre delegam para Use Cases — nenhuma lógica de negócio fica diretamente nos handlers de tasks.
Public API (planejada)¶
Um novo entrypoint para desenvolvedores externos que querem integrar o Spryx aos seus próprios sistemas via uma REST API estável e documentada.
Entrada: src/entrypoints/http/public/ (a ser criado)
Por que um entrypoint separado¶
A App API é acoplada ao modelo de sessão do frontend (JWT + header de tenant). A Public API usará API Keys para autenticação mais simples e stateless — mais adequada para integrações servidor-a-servidor.
Capacidades planejadas¶
- Enviar e receber mensagens entre canais
- Gerenciar contatos e assinaturas de canais
- Disparar workflows programaticamente
- Consultar histórico de conversas
Esta API seguirá um contrato versionado e estável, independente da App API interna.