# rasahq/rasa-calm-demo architecture

> Architecture diagram of the GitHub repository rasahq/rasa-calm-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rasahq/rasa-calm-demo
- Repository: https://github.com/rasahq/rasa-calm-demo

## Overview

##### Project Type and Purpose
- This is a full-stack conversational AI demo built on Rasa’s “CALM” (LLM-native) architecture.
- Purpose: showcase different conversational flows (LLM-based and NLU-based), enterprise search via Qdrant, and end-to-end testing for QA.

##### File Structure Analysis
- Top-level folders:
- actions/        → custom Python actions invoked by the bot
- data/           → training data: CALM flows, NLU stories, prompts
- domain/         → domain definitions for each flow (slots, responses, actions)
- config/         → Rasa pipeline & policy configurations (config.yml plus alternatives)
- e2e_tests/      → end-to-end test scripts, including a mock LLM server under llm_mock_server/
- addons/         → custom enterprise-search component (Qdrant connector)
- scripts/        → utilities: load data into Qdrant, patch dependencies, explore data
- llm_mock_server/→ standalone mock server for simulating LLM responses
- db/             → static JSON files simulating persistent store (contacts, transactions)
- logging_config.yml, endpoints.yml, Makefile, pyproject.toml, etc. (build & run)

##### README Insights
- Describes CALM flows (YAML files under data/flows and domain/flows) coexisting with NLU-based flows.
- Highlights components: Rasa Core, custom actions, Duckling for entity extraction, OpenAI API for LLMs, Qdrant for vector search.
- Outlines dev setup: Rasa Pro license, Python env, Duckling server, training & running via Makefile, E2E tests.

a. Main Components
- User Channel (CLI or Rasa Inspector)
- Rasa Server (Core & Execution Engine)
- Configuration & Data Stores:
- domain/ (slots, responses, actions)
- data/ (flows, NLU training data, prompts)
- models/ (trained Rasa models)
- Action Server (actions/ folder)
- External Services:
- LLM Provider (OpenAI API or Mock LLM Server)
- Duckling Server (entity extraction)
- Qdrant Vector DB (enterprise search)
- JSON DB files (db/ folder for demo persistence)

b. Relationships and Interactions
1. User → Rasa HTTP endpoint (shell or inspect)
2. Rasa NLU Pipeline (config.yml) calls Duckling for date/number extraction
3. Rasa Core applies policies (FlowPolicy, EnterpriseSearchPolicy) to select next step
4. If custom action is needed → Rasa Core makes HTTP request to Action Server
5. Action Server code may:
- Read/write JSON DB
- Call external LLM (OpenAI or mock) for prompt generation or completions
- Query Qdrant for enterprise search via addons/qdrant.py
6. Action Server returns results → Rasa Core → user response

c. Architectural Patterns & Principles
- Separation of Concerns: Core engine vs. custom action execution
- Pluggable Pipelines: configurable via config/*.yml
- Flow-based vs. NLU-based hybrid conversational design
- Microservice-style external dependencies (Duckling, Qdrant, LLM server)

d. Key Technologies & Frameworks
- Rasa Pro (3.14.0): Core, NLU, CALM flows
- Python 3.10+
- Duckling (Docker container)
- OpenAI LLM API (or local mock)
- Qdrant (vector database)
- pytest-style E2E tests with YAML scenarios

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Channel
    User["User Channel\n(CLI / Rasa Inspector)"]:::external

    %% Core Engine
    subgraph "Rasa Core Components"
        RasaServer["Rasa Server\n(Core & Execution Engine)"]:::core
        ConfigYml["config/config.yml"]:::core
        EndpointsYml["endpoints.yml"]:::core
        LoggingConfig["logging_config.yml"]:::core
        DomainShared["domain/_shared.yml"]:::data
        CALMFlows["CALM Flows"]:::data
        DomainFlows["Domain Flows"]:::data
        NLUBFlows["NLU-based Flows"]:::data
        NLUBDomain["domain/nlu-based/*"]:::data
        DomainSearch["domain/search/squad.yml"]:::data
    end

    %% Action Server
    subgraph "Action Server"
        ActionServer["Custom Action Server"]:::actions
        ActionsCode["actions/"]:::actions
        QdrantConnector["addons/qdrant.py"]:::actions
        SearchConfig["config/search-ready-config.yml"]:::core
    end

    %% External Services
    subgraph "External Services"
        Duckling["Duckling Server"]:::external
        QdrantDB["Qdrant Vector DB"]:::external
        LLMAPI["OpenAI API"]:::external
        LLMMock["Mock LLM Server"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        JSONDB["JSON Demo Store\n(db/*.json)"]:::data
        Models["models/"]:::data
    end

    %% Testing & Scripts
    subgraph "Testing & Automation"
        E2ETests["E2E Test Suites"]:::external
        Scripts["scripts/"]:::external
        CI["CI & Makefile"]:::external
    end

    %% Connections
    User -->|"send message"| RasaServer
    RasaServer -->|"load config"| ConfigYml
    RasaServer -->|"serve on"| EndpointsYml
    RasaServer -->|"logging"| LoggingConfig
    RasaServer -->|"load domain"| DomainShared
    RasaServer -->|"load CALM flows"| CALMFlows
    RasaServer -->|"load domain flows"| DomainFlows
    RasaServer -->|"load NLU flows"| NLUBFlows
    RasaServer -->|"load NLU domain"| NLUBDomain
    RasaServer -->|"load search domain"| DomainSearch
    RasaServer -->|"NLU pipeline"| Duckling
    RasaServer -->|"apply policies"| ActionServer
    RasaServer -->|"use models"| Models

    ActionServer -->|"read/write"| JSONDB
    ActionServer -->|"vector search"| QdrantDB
    ActionServer -->|"call LLM"| LLMAPI
    ActionServer -->|"or call mock"| LLMMock
    ActionServer -->|"use connector"| QdrantConnector
    ActionServer -->|"enterprise search cfg"| SearchConfig

    E2ETests -->|"test against"| RasaServer
    E2ETests -->|"mock LLM"| LLMMock
    Scripts -->|"load data"| QdrantDB
    Scripts -->|"patch deps"| ActionsCode
    Scripts -->|"explore data"| JSONDB
    CI -->|"automation"| RasaServer
    CI -->|"run tests"| E2ETests

    %% Click Events
    click ConfigYml "https://github.com/rasahq/rasa-calm-demo/blob/main/config/config.yml"
    click EndpointsYml "https://github.com/rasahq/rasa-calm-demo/blob/main/endpoints.yml"
    click LoggingConfig "https://github.com/rasahq/rasa-calm-demo/blob/main/logging_config.yml"
    click DomainShared "https://github.com/rasahq/rasa-calm-demo/blob/main/domain/_shared.yml"
    click CALMFlows "https://github.com/rasahq/rasa-calm-demo/blob/main/data/flows/*.yml"
    click DomainFlows "https://github.com/rasahq/rasa-calm-demo/blob/main/domain/flows/*.yml"
    click NLUBFlows "https://github.com/rasahq/rasa-calm-demo/tree/main/data/nlu-based/"
    click NLUBDomain "https://github.com/rasahq/rasa-calm-demo/tree/main/domain/nlu-based/"
    click DomainSearch "https://github.com/rasahq/rasa-calm-demo/blob/main/domain/search/squad.yml"
    click ActionsCode "https://github.com/rasahq/rasa-calm-demo/tree/main/actions/"
    click QdrantConnector "https://github.com/rasahq/rasa-calm-demo/blob/main/addons/qdrant.py"
    click SearchConfig "https://github.com/rasahq/rasa-calm-demo/blob/main/config/search-ready-config.yml"
    click JSONDB "https://github.com/rasahq/rasa-calm-demo/blob/main/db/*.json"
    click LLMMock "https://github.com/rasahq/rasa-calm-demo/tree/main/llm_mock_server/"
    click E2ETests "https://github.com/rasahq/rasa-calm-demo/tree/main/e2e_tests/"
    click Scripts "https://github.com/rasahq/rasa-calm-demo/tree/main/scripts/"
    click CI "https://github.com/rasahq/rasa-calm-demo/blob/main/.github/workflows/*.yml"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,color:#1B4F72
    classDef actions fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef external fill:#F9E79F,stroke:#D4AC0D,color:#7D6608
    classDef data fill:#D5D8DC,stroke:#566573,color:#1C2833
```
