Backend Architecture

Cora is an AI-powered Sales Development Representative (SDR) platform. The backend is a Turbo + pnpm monorepo running on Node.js with TypeScript. All services share code through internal packages rather than communicating as separate HTTP microservices.

Services

Service	Port	Purpose
app	3000	Main API Gateway — Express + oRPC routing, auth, WebSocket (Socket.io)
worker	3007	Background job processor — Bull/BullMQ queues, cron jobs
cloudwatch	3003	Centralized structured logging and metrics — AWS CloudWatch
api-docs	8090	This documentation site (VitePress)

Architecture Diagram

Request Flow

1. Client Request → app:3000 receives all API traffic through the oRPC router.
2. Authentication → Better-Auth handles sessions, OAuth (Google), and 2FA via /auth/*.
3. Business Logic → Route handlers call @ce-sdr/lib services (campaigns, leads, email threads, etc.).
4. Data Layer → @ce-sdr/db (Prisma) persists data to MongoDB.
5. Async Jobs → Heavy work (email sending, SMS) is enqueued to BullMQ via Redis and processed by the worker service.
6. Real-time → WebSocket (Socket.io) broadcasts updates to connected clients when jobs complete.
7. Logging → All services forward structured logs to cloudwatch:3003, which writes to AWS CloudWatch.

Multi-tenancy

All business data (leads, campaigns, conversations) is scoped to a Brand. A User can own multiple Brands. API requests are authorized by session + brand membership.

Shared Packages

Package	Role
@ce-sdr/db	Prisma schema (MongoDB), generated client, auto-generated Zod types via zod-prisma-types
@ce-sdr/auth	Better-Auth configuration — email/password, Google OAuth, Stripe OAuth, 2FA, sessions
@ce-sdr/lib	Core business logic — campaigns, leads, email threads, sender accounts, warmup, jobs, webhooks, AI
@ce-sdr/shared	Express middleware (CORS, rate limit, logging), Winston logger, Zod env validation
``	HTTP client to submit logs/metrics to the cloudwatch service