Módulos¶

Cada módulo é um contexto delimitado — ele possui seus modelos de domínio, use cases, repositories e exceções. Módulos nunca importam diretamente uns dos outros.

Mapa de Módulos¶

graph LR
  identity["identity"]
  billing["billing"]
  agent["agent"]
  message["message"]
  connections["connections"]
  asset["asset"]
  audit["audit"]
  notification["notification"]
  tenant_idp["tenant_idp"]

  billing --> identity
  agent --> asset
  agent --> connections
  agent --> billing
  message --> agent
  message --> connections
  tenant_idp --> identity

As setas representam dependências de port (via interfaces + DI), não imports diretos.

identity¶

Gerencia usuários, tenants, autenticação, sessões e controle de acesso.

Entidades principais: User, Tenant, TenantMember, TenantRole, Permission, Session, TenantInvitation, StaffUser

Responsabilidades: - Autenticação por email/senha e Google OAuth - Emissão de JWT e gerenciamento de sessão - Controle de acesso baseado em papéis (RBAC) por tenant - Impersonação de staff para suporte

billing¶

Gerencia o ciclo de vida de assinaturas, entitlements de planos e rastreamento de uso.

Entidades principais: Plan, PlanVersion, Subscription, Entitlement, UsageCounter, Invoice

Responsabilidades: - Assinaturas de tenants em planos versionados - Entitlements por feature (max agentes, max membros, etc.) - Rastreamento de contadores de uso - Registro de faturas via webhooks do Stripe

agent¶

O módulo central de IA. Gerencia agentes, workflows, bases de conhecimento e o pipeline RAG.

Entidades principais: Agent, AgentVersion, Workflow, KnowledgeBase, Document, DocumentVersion, Chunk, CustomTool, AgentThread, AgentMessage

Responsabilidades: - Ciclo de vida de agentes com configurações versionadas - Orquestração de workflows multi-agente (baseado em DAG, com roteamento e nós de aprovação) - Gestão de bases de conhecimento com busca semântica - Pipeline RAG: parse de documento → chunking → embedding (async, via worker) - Memória de IA: turnos de conversa e fatos extraídos

message¶

Gerencia comunicação multi-canal com clientes.

Entidades principais: Contact, Channel, Chat, Message, ContactChannel, ChannelStage

Responsabilidades: - Gestão de contatos (clientes) - Ciclo de vida de canais (WhatsApp, email, SMS) - Roteamento de mensagens de entrada/saída - Histórico de conversas por contato

connections¶

Gerencia credenciais OAuth e o cofre criptografado de credenciais.

Entidades principais: Connection, ConnectionCredentials (Google, Slack, etc.)

Responsabilidades: - Iniciação do fluxo OAuth e tratamento do callback - Armazenamento criptografado de tokens de acesso/refresh (cofre) - Agendamento de refresh de tokens (via worker) - Acesso cross-módulo a credenciais via VaultPort

asset¶

Gerencia uploads de arquivos, storage e ciclo de vida de assets.

Entidades principais: Asset, AssetContent, AssetReference

Responsabilidades: - URLs de upload/download assinadas (compatível com S3) - Rastreamento de conteúdo de assets por versão - Acesso cross-módulo a assets via StoragePort

audit¶

Log imutável de atividades para conformidade e debugging.

Entidades principais: AuditEvent (com Actor discriminado: user | system | api_key)

Responsabilidades: - Registrar todas as ações significativas com ator, timestamp e detalhes estruturados - Consultável por tenant, tipo de ator, recurso e intervalo de datas - Limpeza periódica de eventos antigos (via worker)

notification¶

Entrega de notificações in-app.

Entidades principais: Notification, NotificationPriority

Responsabilidades: - Criar e entregar notificações para usuários - Níveis de prioridade (info, warning, critical) - Dispatch cross-módulo de notificações via NotificationServicePort

tenant_idp¶

Provedor de identidade por tenant para integração SSO.

Responsabilidades: - Gerenciar configuração de autenticação específica por tenant - Ponte entre fluxos de auth do tenant e o módulo identity