Architecture

This section provides an overview of the Open Chat Studio architecture, explaining the core concepts and components that make up the system.

Rather than duplicating details that can drift out of date, this page links to the sources engineers keep current: AGENTS.md, ADRs, CONTEXT.md, and the developer guides.

Significant architectural decisions are recorded as ADRs. See the ADR index for the full list.
For AI-generated architecture diagrams based on this GitHub repo, visit

System Overview

Open Chat Studio is a multi-tenant platform: teams build and configure chatbots through the web UI, then publish them to reach participants — the end users who actually chat with a bot. It sits between two external ecosystems it doesn't own: - Messaging channels — participants reach a chatbot over the web widget, Telegram, WhatsApp, Slack, email, CommCare Connect, or the API directly. - LLM service providers — each team brings its own credentials for the LLM, voice, and tracing providers it wants to use. Internally it's a modular Django app: the web process serves the UI, API, and channel webhooks synchronously, while Celery workers handle everything that shouldn't block a request (message processing, evaluations, document/media ingestion, scheduled events). For the production process topology and backing services (PostgreSQL, Redis), see the Self-Hosting overview; for the third-party services that keep it observable in production, see Monitoring & Observability below.

Technology Stack

See the README's Tech Stack for the full list of languages, frameworks, and deployment targets. A few stack choices carry architectural weight beyond that list:

LLM Abstraction: LangChain provides common chat model interfaces, message structures, and callback hooks that let a single LlmService layer work across providers.
Pipeline builder: the DAG editor is built on React Flow
Chat Widget: standalone StencilJS web component (components/chat_widget), built separately from the main app, embeddable in third-party sites

Key Concepts

See the Concepts User Documentation for product-facing definitions of Chatbots, Channels, Pipelines, Service Providers, and other concepts — or AGENTS.md → Core Concepts for the same concepts summarized for engineers.

For the precise domain language used in code (and by AI coding agents) — e.g. Chatbot vs. Chatbot Version, Working vs. Published Version, Session vs. Participant vs. User, Trace vs. Span — see CONTEXT.md, the canonical glossary kept up to date as the domain model evolves.

Project structure

The project is organized into several Django apps, each responsible for specific functionality. Apps are placed in the apps folder, and each app has its own models, views, serializers, and tests. See the package map for what each app does and how dependencies flow between them.

Not everything lives under apps/ — for example, the chat widget (components/chat_widget) is a standalone StencilJS component with its own build. For the full, up-to-date inventory of key files and folders (settings, webpack config, package management, shared test fixtures/factories, etc.), see AGENTS.md → Key Paths.

A couple of conventions worth knowing:

Django Templates - Centralized in templates/; templates specific to an app go in templates/{app_name}.
Static Files - Frontend source (TypeScript, JavaScript, CSS) lives in assets/ (assets/styles for Tailwind config, assets/javascript for JS/TS modules) and is bundled with Webpack into the static assets served to users. Other static assets, like images, go directly in static/.

Cross-Cutting Concerns

The architectural patterns underlying these concerns — multi-tenancy, versioning, async tasks, API design, LLM/messaging abstractions, and observability — are documented and kept up to date by engineers in AGENTS.md → Architecture. Additional useful pointers below for when working in these areas:

Authentication and Authorization

See the multi-tenancy guide and view security guide for team-scoping and permission patterns.

Monitoring & Observability

Open Chat Studio relies on a small set of external services to keep production healthy: errors are captured and triaged in Sentry, Celery task execution is tracked in Task Badger, and overall uptime is monitored and communicated via BetterStack's status page.