# dograh-hq/dograh architecture

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

- Interactive diagram: https://gitdiagram.com/dograh-hq/dograh
- Repository: https://github.com/dograh-hq/dograh

## Overview

1. **Repository shape**
   - This is a monorepo for a voice-agent platform.
   - The major runtime surfaces are:
     - `api/`: Python backend and orchestration engine
     - `ui/`: Next.js admin/product UI
     - `sdk/`: generated Python and TypeScript client SDKs
     - `docs/`, `examples/`, `evals/`: documentation, samples, and evaluation tooling

2. **Core backend boundary**
   - The backend is the system of record and execution layer.
   - It exposes HTTP routes in `api/routes`, uses a database abstraction in `api/db`, and persists schema changes through Alembic migrations in `api/alembic`.
   - The backend also hosts background jobs in `api/tasks`, plus several specialized service modules for workflow execution, telephony, campaign orchestration, storage, pricing, and authentication.

3. **Primary domain model**
   - The central object is the **workflow**: a graph of nodes that defines a voice agent.
   - Related persistent entities include workflows, workflow definitions/versions, runs, recordings, users, organizations, API keys, telephony configs, tools, knowledge bases, campaigns, and usage/quota records.
   - The architecture is multi-tenant and organization-scoped, with many clients and migrations explicitly handling organization IDs and org-level configuration.

4. **Voice execution path**
   - Live calls flow from telephony or web-based sessions into the runtime engine in `api/services/pipecat` and `api/services/workflow`.
   - This layer coordinates STT, LLM, and TTS providers, manages turn-taking, tool calls, context updates, and recording/audio handling.
   - The runtime is split from the persistence layer: workflow configuration is stored in the DB, then translated into an execution graph and session state at call time.

5. **Telephony subsystem**
   - Telephony is provider-driven and abstracted behind `api/services/telephony`.
   - Provider implementations exist for ARI/Asterisk, Cloudonix, Plivo, Telnyx, Twilio, Vobiz, and Vonage.
   - The provider boundary includes config, serializers, routes/webhooks, transport, and strategy layers, which means telephony vendor logic is isolated from the rest of the app.
   - Call control features such as status updates, transfers, and outbound call setup are handled here.

6. **Workflow editing and validation**
   - The UI workflow builder talks to backend workflow routes and node-spec APIs to render and edit the graph.
   - Node behavior is described by workflow node specs in `api/services/workflow/node_specs`, and the UI mirrors that through `ui/src/components/flow/renderer`.
   - There is a validation/translation boundary for workflow structure, including DTOs, graph constraints, versioning, duplicate detection, and layout logic.

7. **MCP / AI-assisted workflow authoring**
   - `api/mcp_server` provides a Model Context Protocol server for agentic workflow editing and retrieval.
   - It includes tools for creating, saving, and inspecting workflows, plus docs search and workflow code extraction.
   - A TypeScript validator bridge (`api/mcp_server/ts_validator`) is used to parse/generate and validate workflow types, making this subsystem a distinct authoring and safety boundary.

8. **Background processing**
   - Long-running or deferred work is pushed into `api/tasks`.
   - This covers campaign dispatch, knowledge base processing, integration execution, and S3 uploads.
   - The presence of `arq.py` indicates asynchronous job execution rather than synchronous request handling for these workflows.

9. **Files, storage, and media**
   - Storage is abstracted in `api/services/filesystem` with local, S3, MinIO, and null backends.
   - This layer is used for recordings, uploaded documents, generated assets, and other media artifacts.
   - The repo also includes bundled audio assets, which are part of telephony/call-flow behavior rather than static UI content.

10. **Frontend application**
   - `ui/` is a Next.js application that serves the management console.
   - It covers workflow design, telephony configuration, campaigns, recordings, reports, settings, usage, and superadmin views.
   - The UI uses generated OpenAPI clients in `ui/src/client` to communicate with the backend and contains dedicated components for live workflow testing and WebRTC/web call experiences.

11. **SDK and API contract**
   - `sdk/python` and `sdk/typescript` are generated/packaged clients for external integration.
   - They mirror the backend API contract and expose typed workflow-building helpers.
   - This is a key boundary: external users are meant to automate Dograh through SDKs instead of coupling directly to internal code.

12. **Campaigns, reports, and analytics**
   - Campaigns have their own service layer, source sync, orchestrator, rate limiting, and circuit breaker logic.
   - Usage, disposition, run reporting, and daily reporting are separated into dedicated services and routes.
   - Telemetry and product analytics are present through PostHog, while error monitoring and notifications are wired through CI/CD and UI integrations.

13. **Testing, docs, and release plumbing**
   - The repo is heavily test-driven: backend tests cover workflows, telephony, MCP, realtime behavior, and cost calculation; the visualizer and SDKs also have their own tests.
   - Documentation is first-class and generated into a public API reference, deployment guides, and core-concept docs.
   - GitHub Actions, release automation, Docker images, and deployment templates indicate that the repo is intended for both self-hosted and managed cloud delivery.

14. **How to draw the architecture**
   - The main diagram should center on the Python backend as the orchestration hub.
   - Show three inbound channels into it: browser UI, external API/SDK consumers, and telephony/webhook providers.
   - From the backend, branch into persistent storage, async jobs, workflow execution runtime, and provider integrations for LLM/STT/TTS/telephony.
   - Keep the MCP authoring server and SDK generation as adjacent but separate boundaries, since they support workflow creation and integration rather than live call execution.

Main entry points: [`api/routes`](https://github.com/dograh-hq/dograh/tree/main/api/routes) (HTTP Routes), [`api/services/pipecat`](https://github.com/dograh-hq/dograh/tree/main/api/services/pipecat) (Voice Runtime), [`api/services/workflow`](https://github.com/dograh-hq/dograh/tree/main/api/services/workflow) (Workflow Service), [`api/db`](https://github.com/dograh-hq/dograh/tree/main/api/db) (Data Layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_api_routes["HTTP Routes<br/>fastapi routes"]
  node_api_workflow{{"Workflow Service<br/>workflow domain"}}
  node_api_runtime{{"Voice Runtime<br/>execution engine"}}
  node_api_telephony{{"Telephony<br/>provider boundary"}}
  node_api_campaigns{{"Campaigns<br/>orchestration"}}
  node_api_storage[("Storage<br/>files and media")]
  node_api_tasks["Async Jobs<br/>background jobs"]
  node_api_db[("Data Layer<br/>persistence")]
end

subgraph group_frontend["Web UI"]
  node_ui_app["Admin UI<br/>nextjs app"]
  node_ui_flow["Workflow Builder<br/>editor"]
  node_ui_client["API Client<br/>generated client"]
end

subgraph group_contracts["SDKs and authoring"]
  node_api_mcp["MCP Server<br/>authoring server"]
  node_api_ts_validator["TS Validator<br/>bridge"]
  node_sdk_py["Python SDK<br/>generated client"]
  node_sdk_ts["TypeScript SDK<br/>generated client"]
end

subgraph group_support["Docs and tooling"]
  node_docs_site["Docs<br/>documentation site"]
  node_examples_dir["Examples<br/>samples"]
  node_evals_dir["Evals<br/>benchmarks"]
end

node_ui_app -->|"calls"| node_ui_client
node_ui_app -->|"uses"| node_api_routes
node_ui_flow -->|"edits"| node_api_workflow
node_ui_flow -->|"reads/writes"| node_api_routes
node_api_routes -->|"delegates"| node_api_workflow
node_api_routes -->|"delegates"| node_api_telephony
node_api_routes -->|"delegates"| node_api_campaigns
node_api_routes -->|"persists"| node_api_db
node_api_workflow -->|"stores"| node_api_db
node_api_workflow -->|"compiles to"| node_api_runtime
node_api_runtime -->|"connects"| node_api_telephony
node_api_runtime -->|"records"| node_api_storage
node_api_runtime -->|"reads/writes"| node_api_db
node_api_telephony -->|"configures"| node_api_db
node_api_telephony -->|"streams"| node_api_runtime
node_api_campaigns -->|"enqueues"| node_api_tasks
node_api_tasks -->|"uploads"| node_api_storage
node_api_tasks -->|"updates"| node_api_db
node_api_mcp -->|"authors"| node_api_workflow
node_api_mcp -->|"bridges"| node_api_ts_validator
node_sdk_py -->|"consumes"| node_api_routes
node_sdk_ts -->|"consumes"| node_api_routes
node_docs_site -.->|"documents"| node_api_routes
node_examples_dir -.->|"demonstrates"| node_sdk_py
node_examples_dir -.->|"demonstrates"| node_sdk_ts
node_evals_dir -.->|"benchmarks"| node_api_runtime

click node_ui_app "https://github.com/dograh-hq/dograh/tree/main/ui/src/app"
click node_ui_flow "https://github.com/dograh-hq/dograh/tree/main/ui/src/components/flow"
click node_ui_client "https://github.com/dograh-hq/dograh/tree/main/ui/src/client"
click node_api_routes "https://github.com/dograh-hq/dograh/tree/main/api/routes"
click node_api_workflow "https://github.com/dograh-hq/dograh/tree/main/api/services/workflow"
click node_api_runtime "https://github.com/dograh-hq/dograh/tree/main/api/services/pipecat"
click node_api_telephony "https://github.com/dograh-hq/dograh/tree/main/api/services/telephony"
click node_api_campaigns "https://github.com/dograh-hq/dograh/tree/main/api/services/campaign"
click node_api_storage "https://github.com/dograh-hq/dograh/tree/main/api/services/filesystem"
click node_api_tasks "https://github.com/dograh-hq/dograh/tree/main/api/tasks"
click node_api_db "https://github.com/dograh-hq/dograh/tree/main/api/db"
click node_api_mcp "https://github.com/dograh-hq/dograh/tree/main/api/mcp_server"
click node_api_ts_validator "https://github.com/dograh-hq/dograh/tree/main/api/mcp_server/ts_validator"
click node_sdk_py "https://github.com/dograh-hq/dograh/tree/main/sdk/python/src/dograh_sdk"
click node_sdk_ts "https://github.com/dograh-hq/dograh/tree/main/sdk/typescript/src"
click node_docs_site "https://github.com/dograh-hq/dograh/tree/main/docs"
click node_examples_dir "https://github.com/dograh-hq/dograh/tree/main/examples"
click node_evals_dir "https://github.com/dograh-hq/dograh/tree/main/evals"

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_api_routes,node_api_workflow,node_api_runtime,node_api_telephony,node_api_campaigns,node_api_storage,node_api_tasks,node_api_db toneBlue
class node_ui_app,node_ui_flow,node_ui_client toneAmber
class node_api_mcp,node_api_ts_validator,node_sdk_py,node_sdk_ts toneMint
class node_docs_site,node_examples_dir,node_evals_dir toneRose
```

## Components

### Python backend

System of record, orchestration, persistence, and provider integrations.

- [HTTP Routes](https://github.com/dograh-hq/dograh/tree/main/api/routes): fastapi routes · Public and admin HTTP surface for auth, workflows, telephony, campaigns, recordings, and reports. · `api/routes`
- [Workflow Service](https://github.com/dograh-hq/dograh/tree/main/api/services/workflow): workflow domain · Workflow model, DTOs, graph constraints, duplicate detection, versioning, layout, and node specs. · `api/services/workflow`
- [Voice Runtime](https://github.com/dograh-hq/dograh/tree/main/api/services/pipecat): execution engine · Live call execution pipeline coordinating STT, LLM, TTS, turn-taking, tools, context, and recordings. · `api/services/pipecat`
- [Telephony](https://github.com/dograh-hq/dograh/tree/main/api/services/telephony): provider boundary · Vendor-abstracted call control, webhook handling, transport, transfers, and outbound setup. · `api/services/telephony`
- [Campaigns](https://github.com/dograh-hq/dograh/tree/main/api/services/campaign): orchestration · Campaign dispatch, source sync, rate limiting, circuit breaking, and call runner coordination. · `api/services/campaign`
- [Storage](https://github.com/dograh-hq/dograh/tree/main/api/services/filesystem): files and media · Filesystem abstraction for recordings, uploads, generated assets, and artifacts. · `api/services/filesystem`
- [Async Jobs](https://github.com/dograh-hq/dograh/tree/main/api/tasks): background jobs · Deferred processing for campaigns, knowledge bases, integrations, and S3 uploads. · `api/tasks`
- [Data Layer](https://github.com/dograh-hq/dograh/tree/main/api/db): persistence · Database clients, models, and migrations for workflows, runs, users, orgs, keys, configs, and usage. · `api/db`

### Web UI

Next.js management console and workflow builder.

- [Admin UI](https://github.com/dograh-hq/dograh/tree/main/ui/src/app): nextjs app · Management console for workflows, telephony, campaigns, recordings, reports, and settings. · `ui/src/app`
- [Workflow Builder](https://github.com/dograh-hq/dograh/tree/main/ui/src/components/flow): editor · Workflow canvas, node renderer, tester, and version/history editing experience. · `ui/src/components/flow`
- [API Client](https://github.com/dograh-hq/dograh/tree/main/ui/src/client): generated client · Generated OpenAPI client used by the UI to call backend routes. · `ui/src/client`

### SDKs and authoring

Generated clients and agentic workflow authoring boundary.

- [MCP Server](https://github.com/dograh-hq/dograh/tree/main/api/mcp_server): authoring server · Model Context Protocol server for workflow creation, inspection, docs search, and workflow code extraction. · `api/mcp_server`
- [TS Validator](https://github.com/dograh-hq/dograh/tree/main/api/mcp_server/ts_validator): bridge · TypeScript parse/generate/validate bridge used by MCP workflow tooling. · `api/mcp_server/ts_validator`
- [Python SDK](https://github.com/dograh-hq/dograh/tree/main/sdk/python/src/dograh_sdk): generated client · Packaged Python client and typed workflow helpers for external automation. · `sdk/python/src/dograh_sdk`
- [TypeScript SDK](https://github.com/dograh-hq/dograh/tree/main/sdk/typescript/src): generated client · Packaged TypeScript client and typed workflow helpers for external automation. · `sdk/typescript/src`

### Docs and tooling

Docs, examples, evals, and release/deployment tooling.

- [Docs](https://github.com/dograh-hq/dograh/tree/main/docs): documentation site · Public documentation, API reference, guides, and core concepts. · `docs`
- [Examples](https://github.com/dograh-hq/dograh/tree/main/examples): samples · Python and TypeScript examples for creating workflows and triggering calls. · `examples`
- [Evals](https://github.com/dograh-hq/dograh/tree/main/evals): benchmarks · STT benchmark data and visualization tooling for evaluation workflows. · `evals`

## Connections

- Admin UI → API Client: calls · UI fetches data and performs actions through generated API clients.
- Admin UI → HTTP Routes: uses · Browser app consumes backend routes for product features.
- Workflow Builder → Workflow Service: edits · Workflow builder loads node specs, validates graphs, and saves versions.
- Workflow Builder → HTTP Routes: reads/writes · Editor uses workflow routes and node-spec APIs.
- HTTP Routes → Workflow Service: delegates · HTTP layer hands workflow CRUD, validation, and versioning to the workflow domain.
- HTTP Routes → Telephony: delegates · Routes expose telephony configuration, webhooks, and call-control actions.
- HTTP Routes → Campaigns: delegates · Campaign endpoints invoke campaign orchestration services.
- HTTP Routes → Data Layer: persists · Routes read and write multi-tenant records through the database layer.
- Workflow Service → Data Layer: stores · Workflow definitions, versions, runs, recordings, and related metadata are persisted in the database.
- Workflow Service → Voice Runtime: compiles to · Workflow graphs are translated into execution-time session state and runtime pipelines.
- Voice Runtime → Telephony: connects · Live calls enter the runtime through telephony or WebRTC/session transport.
- Voice Runtime → Storage: records · Runtime stores recordings and media through filesystem backends.
- Voice Runtime → Data Layer: reads/writes · Execution updates runs, sessions, context, and usage data.
- Telephony → Data Layer: configures · Telephony providers rely on stored org-scoped configs, numbers, and credentials.
- Telephony → Voice Runtime: streams · Provider webhooks and transports hand call audio and events into the voice engine.
- Campaigns → Async Jobs: enqueues · Long-running campaign work is pushed into background jobs.
- Async Jobs → Storage: uploads · Deferred jobs handle file and S3 upload workflows.
- Async Jobs → Data Layer: updates · Jobs persist campaign progress, processing state, and derived records.
- MCP Server → Workflow Service: authors · MCP tools create, inspect, validate, and save workflows.
- MCP Server → TS Validator: bridges · Workflow toolchain uses TypeScript parsing and validation for safety and code generation.
- Python SDK → HTTP Routes: consumes · Python SDK mirrors backend API contract for external users.
- TypeScript SDK → HTTP Routes: consumes · TypeScript SDK mirrors backend API contract for external users.
- Docs → HTTP Routes: documents · Docs describe public API routes and usage patterns.
- Examples → Python SDK: demonstrates · Python examples show SDK-driven workflow creation and call triggering.
- Examples → TypeScript SDK: demonstrates · TypeScript examples show SDK-driven workflow creation and call triggering.
- Evals → Voice Runtime: benchmarks · Evaluation tooling measures speech/runtime behavior against the execution engine.
