How ralonsom/outreach-crm works
1. Repository shape
- This is a monorepo with three main runtime apps: apps/api (backend control plane), apps/web (Next.js product UI), and apps/voice-agents (separate voice-runtime service).
- Supporting packages under packages/** provide shared contracts, UI/widget code, tool adapters, and security helpers. deploy/** contains production packaging and ops.
2. Backend control plane: apps/api
- The API is a NestJS application organized by business domain rather than by technical layer: auth, billing, campaigns, contacts, inbound, voice, workflows, tools, AI, settings, knowledge base, onboarding, admin, analytics, and webhooks.
- Most product behavior is orchestrated here: it owns REST endpoints, authorization, tenancy checks, persistence, and cross-module coordination.
3. Primary data layer
- apps/api/prisma is the persistence boundary, with Prisma migrations and seed data targeting the canonical database schema.
- The architecture assumes Postgres as the core datastore, with Redis added for caching/coordination (apps/api/src/redis).
- Tests and audits in the repo indicate multi-tenant data isolation, billing state, and encrypted org credentials are important data concerns.
4. Frontend: apps/web
- The web app is a Next.js App Router dashboard for admin and tenant users.
- It is largely a thin client over the API: pages under app/(dashboard) and app/(auth) call dedicated client helpers in apps/web/lib/*.
- State is split between server-rendered routes, client components, and small client stores/hooks for auth, workspace, and assistant context.
5. Voice runtime: apps/voice-agents
- This is a separate service, not just another API module. It handles live call sessions, telephony adapters, speech/LLM provider abstraction, prompt building, caching, and session state.
- Its core boundary is explicit: domain services in core/voice-agent/** are separated from infrastructure adapters in infrastructure/**.
- The runtime talks back to the backend through a backend API client, so the API remains the system of record while voice-agents is the execution engine.
6. Voice execution path
- Telephony events enter through Asterisk/ARI adapters and websocket/media servers in voice-agents/infrastructure/telephony/asterisk.
- Audio and conversation state flow through a coordinated pipeline of STT → LLM → TTS stages, with provider-specific adapters for OpenAI, Deepgram, Azure, ElevenLabs, Gemini, Anthropic, Groq, and others.
- This makes the voice service a real-time, stateful processing pipeline with strict runtime and latency constraints.
7. Inbound messaging and conversational automation
- apps/api/src/inbound is a major subsystem for inbound agents, channels, flows, conversations, tools, sub-agents, and webhooks.
- It includes an execution engine with adapters for email, forms, Instagram, Telegram, web chat, and WhatsApp, plus tool orchestration and handoff logic.
- This area bridges external messages into AI-driven conversations and can escalate to humans or schedule callbacks.
8. Workflow automation engine
- apps/api/src/workflows implements a visual workflow engine with node handlers, triggers, queue processing, cron, enrollment, routing, completion, and hooks.
- Execution is asynchronous and queue-backed, not purely request/response; jobs are monitored and retried through dedicated queue services.
- The node catalog includes action, condition, control, and intelligence nodes, so workflows are a first-class automation runtime.
9. Tooling and external integrations
- apps/api/src/tools, apps/api/src/inbound/engine/tools, and apps/voice-agents/infrastructure/mappers show a shared concept of “tools” across channels.
- Tool execution is mediated through auth/header/param/response-mapping services and protected by policy/security layers in packages/tool-security.
- External services materially shaping the architecture include Stripe billing, email delivery/verification, Google OAuth, Instagram OAuth, and provider-specific AI APIs.
10. Shared packages as contract boundaries
- packages/shared contains canonical domain types and enums used across apps, reducing drift between API and UI/runtime.
- packages/agent-runtime-contracts defines runtime-facing contracts for the voice/browse workers.
- packages/chat-widget is the embeddable web chat client, likely used by apps/api inbound/web-chat flows and the frontend.
- packages/tool-adapters and packages/tool-security encapsulate cross-cutting integration logic so it is not duplicated in each app.
11. Worker and background execution
- apps/browser-tools-worker is a separate worker process, likely for browser-based tool execution or automation tasks.
- The repo also includes apps/api/src/worker.ts, suggesting at least one backend worker entrypoint besides the API server.
- This indicates the system uses multiple processes for web requests, background jobs, and real-time voice execution.
12. Security, tenancy, and governance
- Multi-tenancy and role-based access are central, with guards and decorators around org scoping, billing blocks, onboarding-only access, and super-admin paths.
- The repo has explicit audits and tests for auth, billing security, webhook auth, and input validation, which suggests the architecture is built around strict boundary enforcement.
- Encrypted org credentials and webhook auth services are important security boundaries.
13. Ops and deployment
- Production deployment is container-based: deploy/Dockerfile.*, docker-compose.prod.yml, deploy.sh, rollback.sh, and GitHub Actions drive build/deploy.
- Logging/observability support is present through Loki/Promtail configs and app-level tracing/logging utilities.
- The repo is designed to run as a small set of independently packaged services rather than one unified process.
14. Main end-to-end data flow
- User/admin actions enter through the web app, hit the NestJS API, and persist to Postgres/Redis.
- External events enter through webhooks, channel adapters, or telephony events, then are normalized by API or voice runtime services.
- Long-running automation executes through workflow queues or the voice runtime, while the web app reflects the resulting state back from the API.
Main entry points: app.module.ts API · app.ts Voice agents · layout.tsx Web · inbound Inbound engine
Components 24
Monorepo
Top-level packaging and runtime layout
- outreach-crm · Multi-app CRM/automation platform
API control plane
NestJS backend domains and persistence
- API · Primary backend for product state, auth, orchestration, and integrations
apps/api/src/app.module.ts - Core domains · Auth, billing, campaigns, contacts, settings, admin, analytics, AI
apps/api/src - Inbound engine · Inbound agents, channels, flows, conversations, tools, and webhooks
apps/api/src/inbound - Workflow engine · Queue-backed workflow execution, nodes, triggers, enrollment, and hooks
apps/api/src/workflows - Voice control · Voice bots, calls, metrics, credentials, templates, and system tools
apps/api/src/voice - Prisma store · Canonical persistence boundary with migrations and seed data
apps/api/prisma/schema.prisma - Redis cache · Caching and runtime coordination for the backend
apps/api/src/redis/redis.module.ts - Integrations · Email delivery, verification, webhook dispatch, and provider auth
apps/api/src/integrations
Web app
Next.js dashboard and client layer
- Web · Admin and tenant UI with server routes and client helpers
apps/web/app/layout.tsx - Dashboard routes · Auth, admin, campaigns, contacts, inbound, workflows, settings, and onboarding screens
apps/web/app/(dashboard) - API clients · Dedicated helpers, hooks, and stores that wrap backend calls
apps/web/lib/api.ts - UI shells · Panels, guards, layout chrome, widgets, and domain-specific editors
apps/web/components
Voice runtime
Real-time call processing service
- Voice agents · Separate runtime for live calls, prompt assembly, and provider orchestration
apps/voice-agents/bootstrap/app.ts - Voice core · Session, conversation, prompt, and call coordination services
apps/voice-agents/core/voice-agent/services/VoiceAgentOrchestrator.ts - AI pipeline · Concurrent audio/conversation pipeline and provider abstractions
apps/voice-agents/infrastructure/ai-providers/adapters/concurrent-pipeline/ConcurrentPipelineAdapter.ts - Telephony adapters · WebSocket/media servers and telephony integration for live sessions
apps/voice-agents/infrastructure/telephony/asterisk/AsteriskAdapter.ts - Backend client · API client, session store, cache, and credential helpers back to the control plane
apps/voice-agents/infrastructure/backend-client/BackendApiClient.ts
Shared packages
Cross-app contracts and integration helpers
- Shared contracts · Canonical enums, DTO-ish types, and cross-app shared models
packages/shared/src/index.ts - Chat widget · Reusable web chat package for inbound or site-embedded conversation entry points
packages/chat-widget/src/index.ts - Tool adapters · Shared tool mapping/adaptation layer for model and channel integrations
packages/tool-adapters/src/index.ts - Tool security · HTTP tool policy, response limits, and PII masking protections
packages/tool-security/src/index.ts
Deployment
Container and production operations
- Browser worker · Separate worker process for browser-based automation or tool execution
apps/browser-tools-worker/src/index.ts - Deploy ops · Production Dockerfiles, compose, deploy/rollback scripts, and observability configs
deploy/docker-compose.prod.yml
Connections 30
- outreach-crm → API: ships · Monorepo packages and deploys the backend service
- outreach-crm → Web: ships · Monorepo packages and deploys the dashboard
- outreach-crm → Voice agents: ships · Monorepo packages and deploys the voice runtime
- outreach-crm → Browser worker: ships · Separate worker process for automation tasks
- API → Core domains: coordinates · Main NestJS app composes business-domain modules
- API → Inbound engine: orchestrates · Inbound agents, channels, flows, and conversations
- API → Workflow engine: runs · Queue-backed workflow engine and node execution
- API → Voice control: administers · Voice bot and call management APIs
- API → Integrations: integrates · External services and webhook boundaries
- API → Prisma store: persists · Canonical data model and migrations
- API → Redis cache: coordinates · Redis-backed cache and coordination
- Web → Dashboard routes: renders · App Router dashboard pages and screens
- Web → API clients: calls · Thin client layer over backend APIs
- Web → UI shells: composes · Shared UI shells, guards, and editors
- Voice agents → Voice core: orchestrates · Session lifecycle and conversation control
- Voice agents → AI pipeline: processes · STT, LLM, and TTS execution pipeline
- Voice agents → Telephony adapters: connects · Asterisk/ARI and media websocket adapters
- Voice agents → Backend client: syncs · Backend API client and shared session state
- Shared contracts → API: shared by · Canonical types consumed by the backend
- Shared contracts → Web: shared by · Shared contracts used by the dashboard
- Shared contracts → Voice agents: shared by · Shared runtime contracts and value objects
- Chat widget → Inbound engine: feeds · Embeddable chat entry point for inbound conversations
- Chat widget → Web: embedded in · Reusable widget/client code for product surfaces
- Tool adapters → Inbound engine: powers · Tool mapping and execution adapters for channels
- Tool adapters → Voice agents: powers · Tool mapping for voice model integrations
- Tool security → Inbound engine: protects · Tool and HTTP security boundaries
- Tool security → Voice agents: protects · Policy and response constraints for runtime tools
- API → Deploy ops: deployed with · Backend is packaged for production via container ops
- Web → Deploy ops: deployed with · Dashboard is packaged for production via container ops
- Voice agents → Deploy ops: deployed with · Voice runtime is packaged separately for production