Guia
Visão Geral da Arquitetura
Mapa completo do ecossistema QueroTruck: 23+ microsserviços, padrões arquiteturais, fluxo de eventos e comunicação entre serviços.
Atualizado em 2026-04-18
Mapa de Serviços
- QueroTruck.Web.Api — API principal do marketplace (anúncios, engajamento, , busca semântica)
- QueroTruck.Auth — Autenticação OIDC, RBAC, WebAuthn, social login
- QueroTruck.Tracking — Ingestão de eventos, analytics, wallet, ML features
- QueroTruck.Nexus — CRM, automações, timeline, gestão de leads/deals
- QueroTruck.Rebecca — Camada de IA (sinais de lead, copiloto CRM, banners, TTS)
- QueroTruck.Suggesty — Motor de decisão de contato, A/B testing, qualificação de leads
- QueroTruck.Mailing — Dispatch multicanal (email, SMS, WhatsApp, push, in-app)
- QueroTruck.Chat — Mensagens em tempo real entre compradores e vendedores
- QueroTruck.Payments — Processamento de pagamentos (Stripe), assinaturas
- QueroTruck.Profiles — Perfis de usuário e empresa
- QueroTruck.Locations — Geolocalização (MaxMind GeoIP)
- QueroTruck.Kpis — Métricas e dashboards analíticos
- QueroTruck.Social — Integrações com redes sociais
- QueroTruck.Realtime — Comunicação WebSocket/SignalR em tempo real
- QueroTruck.EventProbe — Diagnóstico e inspeção de eventos RabbitMQ
- QueroTruck.Webhooks — Gestão de webhooks entrada/saída
- QueroTruck.Vault — Armazenamento seguro de segredos e PII
- QueroTruck.Invoices — Geração e gestão de faturas
- QueroTruck.Connect — Studio de automações no-code (Next.js + Prisma)
- CodeBrain — Indexação de código e análise por IA (Python, pgvector, Neo4j)
Padrões Arquiteturais
- Clean Architecture: Api → Application → Domain → Infrastructure por serviço
- Domain-Driven Design (DDD): bounded contexts por serviço, entidades, value objects
- Event-Driven: comunicação assíncrona via RabbitMQ + MassTransit 8.5
- Outbox/Inbox Pattern: MassTransit EF Core para exatamente-uma-vez na entrega
- CQRS-like: eventos de domínio separados de queries, cold vs hot paths
- Deduplication em 3 camadas: request-level, processed_events, chaves determinísticas
- Observabilidade: OpenTelemetry + correlation IDs (X-Correlation-Id, X-Causation-Id, X-Tenant-Id)
Stack de Tecnologia
- Backend: .NET 8, ASP.NET Core, EF Core 8.0, MassTransit 8.5, Hangfire
- Banco de dados: PostgreSQL por serviço (schemas isolados), pgvector para embeddings
- Messaging: RabbitMQ via MassTransit (suporte a Azure Service Bus configurável)
- Frontend: Next.js 15 (App Router), TypeScript 5.7, Tailwind CSS 4, React Query
- Monorepo: pnpm 9.15.9 + Turborepo v2.5.8
- IA: OpenAI (embeddings, moderation, vision), ElevenLabs (TTS)
- Python: CodeBrain com FastAPI, pgvector, Neo4j (grafo de código)
- Containers: Docker + Docker Compose (dev), Kubernetes-ready (prod)
Fluxo Principal de Eventos
- 1. Frontend/App → Tracking (ingestão de evento de interação)
- 2. Tracking → Nexus (tracking.crm.interaction.observed — hot path CRM)
- 3. Tracking → Rebecca/Suggesty (features, scores, sinais)
- 4. Rebecca → Suggesty (lead.ai.signals.updated — propensidades, canal, hora)
- 5. Suggesty → Mailing (contact.attempt.planned — plano de contato)
- 6. Mailing → todos (dispatch.sent/delivered/clicked — feedback loop)
- 7. Nexus → Suggesty (communication.plan.requested — request explícito de CRM)
Nexus como hub de automações
O Nexus orquestra automações CRM e pode solicitar contatos ao Suggesty via nexus.communication.plan.requested. Suggesty é o único publisher de planos de contato para o Mailing.
Convenções de Nomes
- Eventos de domínio: dot.case — ex: tracking.crm.interaction.observed
- Contratos de evento: PascalCase + EventContract suffix — ex: TrackingCrmInteractionObservedEventContract
- Breaking change de payload: nova versão maior do contrato (v1 → v2)
- Campos novos opcionais: compatibilidade forward/backward sem bump de versão
- Tabelas de banco: snake_case, schema isolado por serviço
- APIs REST: /v1/<recurso> com kebab-case
- Correlation IDs: X-Correlation-Id em todos os requests inter-serviços