# ralonsom/outreach-crm architecture

> Architecture diagram of the GitHub repository ralonsom/outreach-crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ralonsom/outreach-crm
- Repository: https://github.com/ralonsom/outreach-crm

## Overview

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: [`apps/api/src/app.module.ts`](https://github.com/ralonsom/outreach-crm/blob/main/apps/api/src/app.module.ts) (API), [`apps/voice-agents/bootstrap/app.ts`](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/bootstrap/app.ts) (Voice agents), [`apps/web/app/layout.tsx`](https://github.com/ralonsom/outreach-crm/blob/main/apps/web/app/layout.tsx) (Web), [`apps/api/src/inbound`](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/inbound) (Inbound engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_monorepo["outreach-crm<br/>monorepo"]
end

subgraph group_api["API control plane"]
  node_api_app["API<br/>NestJS control plane<br/>[app.module.ts]"]
  node_api_domains["Core domains<br/>business modules"]
  node_api_inbound["Inbound engine<br/>conversation automation"]
  node_api_workflows["Workflow engine<br/>async automation runtime"]
  node_api_voice["Voice control<br/>voice administration"]
  node_api_data[("Prisma store<br/>Postgres schema<br/>[schema.prisma]")]
  node_api_cache[("Redis cache<br/>coordination cache<br/>[redis.module.ts]")]
  node_api_integrations["Integrations<br/>email/webhooks/ oauth"]
end

subgraph group_web["Web app"]
  node_web_app["Web<br/>Next.js dashboard<br/>[layout.tsx]"]
  node_web_routes["Dashboard routes<br/>app router views"]
  node_web_clients["API clients<br/>frontend data layer<br/>[api.ts]"]
  node_web_ui["UI shells<br/>react components"]
end

subgraph group_voice["Voice runtime"]
  node_voice_app["Voice agents<br/>real-time service<br/>[app.ts]"]
  node_voice_core["Voice core<br/>domain orchestrator"]
  node_voice_pipeline["AI pipeline<br/>STT→LLM→TTS"]
  node_voice_telephony["Telephony adapters<br/>Asterisk/ARI runtime<br/>[AsteriskAdapter.ts]"]
  node_voice_backend["Backend client<br/>system-of-record bridge"]
end

subgraph group_shared["Shared packages"]
  node_packages_shared["Shared contracts<br/>domain types<br/>[index.ts]"]
  node_packages_widget["Chat widget<br/>embeddable client<br/>[index.ts]"]
  node_packages_tools["Tool adapters<br/>integration mappers<br/>[index.ts]"]
  node_packages_security["Tool security<br/>security helpers<br/>[index.ts]"]
end

subgraph group_deploy["Deployment"]
  node_browser_worker["Browser worker<br/>auxiliary worker<br/>[index.ts]"]
  node_deploy_ops["Deploy ops<br/>docker and scripts"]
end

node_monorepo -->|"ships"| node_api_app
node_monorepo -->|"ships"| node_web_app
node_monorepo -->|"ships"| node_voice_app
node_monorepo -->|"ships"| node_browser_worker
node_api_app -->|"coordinates"| node_api_domains
node_api_app -->|"orchestrates"| node_api_inbound
node_api_app -->|"runs"| node_api_workflows
node_api_app -->|"administers"| node_api_voice
node_api_app -->|"integrates"| node_api_integrations
node_api_app -->|"persists"| node_api_data
node_api_app -->|"coordinates"| node_api_cache
node_web_app -->|"renders"| node_web_routes
node_web_app -->|"calls"| node_web_clients
node_web_app -->|"composes"| node_web_ui
node_voice_app -->|"orchestrates"| node_voice_core
node_voice_app -->|"processes"| node_voice_pipeline
node_voice_app -->|"connects"| node_voice_telephony
node_voice_app -->|"syncs"| node_voice_backend
node_packages_shared -->|"shared by"| node_api_app
node_packages_shared -->|"shared by"| node_web_app
node_packages_shared -->|"shared by"| node_voice_app
node_packages_widget -->|"feeds"| node_api_inbound
node_packages_widget -->|"embedded in"| node_web_app
node_packages_tools -->|"powers"| node_api_inbound
node_packages_tools -->|"powers"| node_voice_app
node_packages_security -->|"protects"| node_api_inbound
node_packages_security -->|"protects"| node_voice_app
node_api_app -.->|"deployed with"| node_deploy_ops
node_web_app -.->|"deployed with"| node_deploy_ops
node_voice_app -.->|"deployed with"| node_deploy_ops

click node_api_app "https://github.com/ralonsom/outreach-crm/blob/main/apps/api/src/app.module.ts"
click node_api_domains "https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src"
click node_api_inbound "https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/inbound"
click node_api_workflows "https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/workflows"
click node_api_voice "https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/voice"
click node_api_data "https://github.com/ralonsom/outreach-crm/blob/main/apps/api/prisma/schema.prisma"
click node_api_cache "https://github.com/ralonsom/outreach-crm/blob/main/apps/api/src/redis/redis.module.ts"
click node_api_integrations "https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/integrations"
click node_web_app "https://github.com/ralonsom/outreach-crm/blob/main/apps/web/app/layout.tsx"
click node_web_routes "https://github.com/ralonsom/outreach-crm/tree/main/apps/web/app/(dashboard)"
click node_web_clients "https://github.com/ralonsom/outreach-crm/blob/main/apps/web/lib/api.ts"
click node_web_ui "https://github.com/ralonsom/outreach-crm/tree/main/apps/web/components"
click node_voice_app "https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/bootstrap/app.ts"
click node_voice_core "https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/core/voice-agent/services/VoiceAgentOrchestrator.ts"
click node_voice_pipeline "https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/ai-providers/adapters/concurrent-pipeline/ConcurrentPipelineAdapter.ts"
click node_voice_telephony "https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/telephony/asterisk/AsteriskAdapter.ts"
click node_voice_backend "https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/backend-client/BackendApiClient.ts"
click node_packages_shared "https://github.com/ralonsom/outreach-crm/blob/main/packages/shared/src/index.ts"
click node_packages_widget "https://github.com/ralonsom/outreach-crm/blob/main/packages/chat-widget/src/index.ts"
click node_packages_tools "https://github.com/ralonsom/outreach-crm/blob/main/packages/tool-adapters/src/index.ts"
click node_packages_security "https://github.com/ralonsom/outreach-crm/blob/main/packages/tool-security/src/index.ts"
click node_browser_worker "https://github.com/ralonsom/outreach-crm/blob/main/apps/browser-tools-worker/src/index.ts"
click node_deploy_ops "https://github.com/ralonsom/outreach-crm/blob/main/deploy/docker-compose.prod.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_monorepo toneBlue
class node_api_app,node_api_domains,node_api_inbound,node_api_workflows,node_api_voice,node_api_data,node_api_cache,node_api_integrations toneAmber
class node_web_app,node_web_routes,node_web_clients,node_web_ui toneMint
class node_voice_app,node_voice_core,node_voice_pipeline,node_voice_telephony,node_voice_backend toneRose
class node_packages_shared,node_packages_widget,node_packages_tools,node_packages_security toneIndigo
class node_browser_worker,node_deploy_ops toneTeal
```

## Components

### Monorepo

Top-level packaging and runtime layout

- **outreach-crm**: monorepo · Multi-app CRM/automation platform

### API control plane

NestJS backend domains and persistence

- [API](https://github.com/ralonsom/outreach-crm/blob/main/apps/api/src/app.module.ts): NestJS control plane · Primary backend for product state, auth, orchestration, and integrations · `apps/api/src/app.module.ts`
- [Core domains](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src): business modules · Auth, billing, campaigns, contacts, settings, admin, analytics, AI · `apps/api/src`
- [Inbound engine](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/inbound): conversation automation · Inbound agents, channels, flows, conversations, tools, and webhooks · `apps/api/src/inbound`
- [Workflow engine](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/workflows): async automation runtime · Queue-backed workflow execution, nodes, triggers, enrollment, and hooks · `apps/api/src/workflows`
- [Voice control](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/voice): voice administration · Voice bots, calls, metrics, credentials, templates, and system tools · `apps/api/src/voice`
- [Prisma store](https://github.com/ralonsom/outreach-crm/blob/main/apps/api/prisma/schema.prisma): Postgres schema · Canonical persistence boundary with migrations and seed data · `apps/api/prisma/schema.prisma`
- [Redis cache](https://github.com/ralonsom/outreach-crm/blob/main/apps/api/src/redis/redis.module.ts): coordination cache · Caching and runtime coordination for the backend · `apps/api/src/redis/redis.module.ts`
- [Integrations](https://github.com/ralonsom/outreach-crm/tree/main/apps/api/src/integrations): email/webhooks/ oauth · Email delivery, verification, webhook dispatch, and provider auth · `apps/api/src/integrations`

### Web app

Next.js dashboard and client layer

- [Web](https://github.com/ralonsom/outreach-crm/blob/main/apps/web/app/layout.tsx): Next.js dashboard · Admin and tenant UI with server routes and client helpers · `apps/web/app/layout.tsx`
- [Dashboard routes](https://github.com/ralonsom/outreach-crm/tree/main/apps/web/app/(dashboard)): app router views · Auth, admin, campaigns, contacts, inbound, workflows, settings, and onboarding screens · `apps/web/app/(dashboard)`
- [API clients](https://github.com/ralonsom/outreach-crm/blob/main/apps/web/lib/api.ts): frontend data layer · Dedicated helpers, hooks, and stores that wrap backend calls · `apps/web/lib/api.ts`
- [UI shells](https://github.com/ralonsom/outreach-crm/tree/main/apps/web/components): react components · Panels, guards, layout chrome, widgets, and domain-specific editors · `apps/web/components`

### Voice runtime

Real-time call processing service

- [Voice agents](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/bootstrap/app.ts): real-time service · Separate runtime for live calls, prompt assembly, and provider orchestration · `apps/voice-agents/bootstrap/app.ts`
- [Voice core](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/core/voice-agent/services/VoiceAgentOrchestrator.ts): domain orchestrator · Session, conversation, prompt, and call coordination services · `apps/voice-agents/core/voice-agent/services/VoiceAgentOrchestrator.ts`
- [AI pipeline](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/ai-providers/adapters/concurrent-pipeline/ConcurrentPipelineAdapter.ts): STT→LLM→TTS · Concurrent audio/conversation pipeline and provider abstractions · `apps/voice-agents/infrastructure/ai-providers/adapters/concurrent-pipeline/ConcurrentPipelineAdapter.ts`
- [Telephony adapters](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/telephony/asterisk/AsteriskAdapter.ts): Asterisk/ARI runtime · WebSocket/media servers and telephony integration for live sessions · `apps/voice-agents/infrastructure/telephony/asterisk/AsteriskAdapter.ts`
- [Backend client](https://github.com/ralonsom/outreach-crm/blob/main/apps/voice-agents/infrastructure/backend-client/BackendApiClient.ts): system-of-record bridge · 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](https://github.com/ralonsom/outreach-crm/blob/main/packages/shared/src/index.ts): domain types · Canonical enums, DTO-ish types, and cross-app shared models · `packages/shared/src/index.ts`
- [Chat widget](https://github.com/ralonsom/outreach-crm/blob/main/packages/chat-widget/src/index.ts): embeddable client · Reusable web chat package for inbound or site-embedded conversation entry points · `packages/chat-widget/src/index.ts`
- [Tool adapters](https://github.com/ralonsom/outreach-crm/blob/main/packages/tool-adapters/src/index.ts): integration mappers · Shared tool mapping/adaptation layer for model and channel integrations · `packages/tool-adapters/src/index.ts`
- [Tool security](https://github.com/ralonsom/outreach-crm/blob/main/packages/tool-security/src/index.ts): security helpers · HTTP tool policy, response limits, and PII masking protections · `packages/tool-security/src/index.ts`

### Deployment

Container and production operations

- [Browser worker](https://github.com/ralonsom/outreach-crm/blob/main/apps/browser-tools-worker/src/index.ts): auxiliary worker · Separate worker process for browser-based automation or tool execution · `apps/browser-tools-worker/src/index.ts`
- [Deploy ops](https://github.com/ralonsom/outreach-crm/blob/main/deploy/docker-compose.prod.yml): docker and scripts · Production Dockerfiles, compose, deploy/rollback scripts, and observability configs · `deploy/docker-compose.prod.yml`

## Connections

- 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
