Visão Geral da Arquitetura¶

O que é o Spryx Backend?¶

O Spryx Backend é um monólito modular — uma única aplicação implantável organizada em contextos delimitados (módulos) que impõem separação estrita de responsabilidades, sem a complexidade de microsserviços.

Monólito Modular¶

O sistema é uma base de código, um banco de dados, múltiplos contextos delimitados.

Cada módulo possui seu domínio:

• Sem imports diretos entre módulos — módulos se comunicam através de interfaces (Ports) conectadas via injeção de dependência
• Infraestrutura compartilhada em src/modules/shared/ — banco de dados, Redis, email, storage — mas a lógica de domínio nunca vaza entre módulos
• Fácil de desenvolver e testar — sem overhead de sistema distribuído, sem service discovery, sem chamadas de rede entre módulos
• Fácil de extrair — se um módulo precisar escalar independentemente no futuro, pode ser extraído como serviço separado sem alterar sua lógica interna

Isso nos dá o isolamento de microsserviços com a simplicidade de um monólito.

Contexto do Sistema¶

graph TD
  Tenant["🏢 Tenant\n(Cliente SaaS)"]
  Staff["👤 Staff\n(Time Interno)"]
  Developer["🧑‍💻 Desenvolvedor Externo\n(Integração)"]

  AppAPI["App API\nFastAPI · REST + WebSocket"]
  BackofficeAPI["Backoffice API\nFastAPI · REST"]
  Worker["Celery Worker\nTarefas em Background"]
  PublicAPI["Public API\nFastAPI · REST  ⏳ planejada"]

  DB[("PostgreSQL\nSupabase")]
  Redis[("Redis")]
  OpenAI["OpenAI"]
  Stripe["Stripe"]
  WhatsApp["WhatsApp\nWAHA"]
  S3["S3 Storage"]

  Tenant -->|REST + WebSocket| AppAPI
  Staff -->|REST| BackofficeAPI
  Developer -->|REST · API Key| PublicAPI

  AppAPI --> DB
  BackofficeAPI --> DB
  Worker --> DB
  PublicAPI --> DB

  AppAPI <-->|enqueue / results| Redis
  Worker <-->|dequeue| Redis

  Worker --> OpenAI
  Worker --> S3
  AppAPI --> WhatsApp
  AppAPI --> Stripe
  BackofficeAPI --> Stripe

Módulos¶

A aplicação é dividida em 9 contextos delimitados, cada um responsável por um domínio distinto:

graph LR
  identity["identity\nUsuários, Tenants, Auth, Papéis"]
  billing["billing\nPlanos, Assinaturas, Entitlements"]
  agent["agent\nAgentes IA, Workflows, Bases de Conhecimento"]
  message["message\nContatos, Canais, Conversas"]
  connections["connections\nOAuth, Cofre de Credenciais"]
  asset["asset\nStorage de Arquivos, Documentos"]
  audit["audit\nLog de Atividades"]
  notification["notification\nNotificações In-app"]
  tenant_idp["tenant_idp\nSSO do Tenant"]

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