# dimagi/open-chat-studio architecture

> Architecture diagram of the GitHub repository dimagi/open-chat-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dimagi/open-chat-studio
- Repository: https://github.com/dimagi/open-chat-studio

## Overview

##### Main components
- Frontend/UI Layer:
- Web templates (using Django’s templating engine).
- Client-side JavaScript components and assets (including the chat widget and pipeline components).
- Static assets such as CSS, images, and JS that enable dynamic features.
- Backend (Django Monolith):
- Multiple Django “apps” organized under the apps/ folder. Each app focuses on a distinct domain (e.g., chat, experiments, pipelines, service_providers, admin, etc.).
- A core “gpt_playground” module that appears to house the global settings (settings.py, wsgi.py) and Celery configuration (celery.py) for background task processing.
- Background/Asynchronous Processing:
- Celery workers (with commands demonstrated in the README and settings in the gpt_playground package) that handle asynchronous jobs (like querying LLM services).
- Redis or another broker (as implied by the docker-compose setup) to support Celery.
- Database:
- A relational database (given Django’s ORM and numerous migrations in every app).
- Migrations indicate that schema evolution is handled for every module.
- External Services/Integrations:
- Integrations via service_providers (authentication services, LLM service integration, messaging service, etc.).
- API endpoints under apps/api as well as external API wrappers (e.g., apps/api/openai.py).
- Possibly Slack, SSO, and channels integrations that appear in designated apps.
- Developer Tools/DevOps:
- Docker and docker-compose (for local dev environment).
- CI/CD workflows in the .github/workflows directory.
- Tools for code quality, automated tests (pytest), linting (ruff), and pre-commit hooks.

##### Relationships and Interactions
- Database interactions are central – show that various Django apps persist and retrieve data from a central “Database” component.

##### Architectural Patterns/Design Principles
- Modular/Separation of Concerns: Emphasize that each domain (chat, experiments, pipelines, etc.) is encapsulated as a separate Django app.
- MVC/MVT: Although Django follows the Model-View-Template paradigm, show that models (with migrations), views, and templates are clearly separated.
- Asynchronous Processing: Illustrate the asynchronous processing of long-running tasks (such as LLM responses) via Celery.
- External Abstraction: Indicate that there is a layer abstracting communication with external APIs (service_providers and channels).

##### Relevant Technologies and Frameworks
- Core: Python 3.11 and Django.
- Background tasks: Celery with Redis (or a similar messaging broker).
- Frontend: JavaScript/TypeScript, Tailwind CSS, Alpine.js, and components built with Stencil and/or React (as seen in assets/javascript and components folders).
- Containerization: Docker (with Dockerfile and docker-compose-dev.yml) and Heroku deployment support.
- Code Quality: Tools like pre-commit, ruff, and pytest.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User / Browser"]:::user

    subgraph "Frontend Layer"
        FT["Web Templates (Django)"]:::frontend
        JS["JS Components & Assets"]:::frontend
    end

    subgraph "Backend Layer"
        CORE["Core Module (gpt_playground)"]:::backend
        subgraph "Django Apps"
            CHAT["Chat (apps/chat)"]:::backend
            EXP["Experiments (apps/experiments)"]:::backend
            PIPE["Pipelines (apps/pipelines)"]:::backend
            CHAN["Channels & Messaging (apps/channels)"]:::backend
            SERV["Service Providers (apps/service_providers)"]:::backend
            API["API Endpoints (apps/api)"]:::backend
        end
    end

    subgraph "Infrastructure"
        DB["Database"]:::database
        MB["Message Broker (Redis)"]:::infrastructure
        CW["Celery Workers"]:::infrastructure
        EXT["External Services (OpenAI,Slack,SSO)"]:::external
    end

    subgraph "DevOps & Developer Tools"
        CI["CI/CD (.github/workflows)"]:::devops
        DF["Containerization (Dockerfile)"]:::devops
        DC["Containerization (docker-compose-dev.yml)"]:::devops
    end

    %% Connections from User to Frontend
    U -->|"accesses"| FT
    U -->|"accesses"| JS

    %% Frontend sends requests to Backend
    FT -->|"renders requests to"| CORE
    JS -->|"sends AJAX calls to"| CORE

    %% Core routing to Django Apps
    CORE -->|"routes to"| CHAT
    CORE -->|"routes to"| EXP
    CORE -->|"routes to"| PIPE
    CORE -->|"routes to"| CHAN
    CORE -->|"routes to"| SERV
    CORE -->|"routes to"| API

    %% Database interactions with Core and Apps
    CORE -->|"DB operations"| DB
    CHAT -->|"DB operations"| DB
    EXP -->|"DB operations"| DB
    PIPE -->|"DB operations"| DB
    CHAN -->|"DB operations"| DB
    SERV -->|"DB operations"| DB
    API -->|"DB operations"| DB

    %% Asynchronous processing via message broker and celery
    CORE -->|"sends tasks to"| MB
    CHAT -->|"sends tasks to"| MB
    EXP -->|"sends tasks to"| MB
    PIPE -->|"sends tasks to"| MB
    MB -->|"queues tasks to"| CW

    %% External integrations (from Service Providers and API)
    SERV -->|"integrates with"| EXT
    API -->|"externalAPICalls"| EXT

    %% Developer Tools supporting Backend
    CI --- CORE
    DF --- CORE
    DC --- CORE

    %% Click Events
    click FT "https://github.com/dimagi/open-chat-studio/tree/main/templates/"
    click JS "https://github.com/dimagi/open-chat-studio/tree/main/assets/"
    click CHAT "https://github.com/dimagi/open-chat-studio/tree/main/apps/chat/"
    click EXP "https://github.com/dimagi/open-chat-studio/tree/main/apps/experiments/"
    click PIPE "https://github.com/dimagi/open-chat-studio/tree/main/apps/pipelines/"
    click CHAN "https://github.com/dimagi/open-chat-studio/tree/main/apps/channels/"
    click SERV "https://github.com/dimagi/open-chat-studio/tree/main/apps/service_providers/"
    click CORE "https://github.com/dimagi/open-chat-studio/tree/main/gpt_playground/"
    click API "https://github.com/dimagi/open-chat-studio/tree/main/apps/api/"
    click CI "https://github.com/dimagi/open-chat-studio/tree/main/.github/workflows/"
    click DF "https://github.com/dimagi/open-chat-studio/tree/main/Dockerfile"
    click DC "https://github.com/dimagi/open-chat-studio/blob/main/docker-compose-dev.yml"

    %% Styles
    classDef user fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef frontend fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef backend fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef database fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef infrastructure fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef devops fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
```
