How dograh-hq/dograh works
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: routes HTTP Routes · pipecat Voice Runtime · workflow Workflow Service · db Data Layer
Components 18
Python backend
System of record, orchestration, persistence, and provider integrations.
- HTTP Routes · Public and admin HTTP surface for auth, workflows, telephony, campaigns, recordings, and reports.
api/routes - Workflow Service · Workflow model, DTOs, graph constraints, duplicate detection, versioning, layout, and node specs.
api/services/workflow - Voice Runtime · Live call execution pipeline coordinating STT, LLM, TTS, turn-taking, tools, context, and recordings.
api/services/pipecat - Telephony · Vendor-abstracted call control, webhook handling, transport, transfers, and outbound setup.
api/services/telephony - Campaigns · Campaign dispatch, source sync, rate limiting, circuit breaking, and call runner coordination.
api/services/campaign - Storage · Filesystem abstraction for recordings, uploads, generated assets, and artifacts.
api/services/filesystem - Async Jobs · Deferred processing for campaigns, knowledge bases, integrations, and S3 uploads.
api/tasks - Data Layer · 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 · Management console for workflows, telephony, campaigns, recordings, reports, and settings.
ui/src/app - Workflow Builder · Workflow canvas, node renderer, tester, and version/history editing experience.
ui/src/components/flow - API 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 · Model Context Protocol server for workflow creation, inspection, docs search, and workflow code extraction.
api/mcp_server - TS Validator · TypeScript parse/generate/validate bridge used by MCP workflow tooling.
api/mcp_server/ts_validator - Python SDK · Packaged Python client and typed workflow helpers for external automation.
sdk/python/src/dograh_sdk - TypeScript SDK · Packaged TypeScript client and typed workflow helpers for external automation.
sdk/typescript/src
Docs and tooling
Docs, examples, evals, and release/deployment tooling.
Connections 26
- 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.