# sirocco-ventures/raggenie architecture

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

- Interactive diagram: https://gitdiagram.com/sirocco-ventures/raggenie
- Repository: https://github.com/sirocco-ventures/raggenie

## Overview

Based on our analysis of the file tree and the README, RAGGENIE is a low-code, open-source tool that enables users to quickly build conversational AI applications using a Retrieval Augmented Generation (RAG) approach. The project provides both a backend API (written in Python) and a frontend application (built with a React/Vite stack) as well as modular support for plugins, various data connectors, multiple LLM inference providers, and vector database integrations.

##### Main Components
- Frontend/UI Layer: This resides in the “ui” directory. It involves the chat widget, configuration pages, dashboards, and other components for user interaction. Mention that it communicates with the backend API via REST calls.
- Backend/API Layer: Found in the “app” directory. Key subfolders include:
– “app/api/v1”: Contains the API endpoints (e.g., auth, llmchat, connector, provider).
– “app/chain”: Contains several chain modules that orchestrate the conversation flow, capability logic, context/retrieval management, and post-processing.
– “app/base”: Contains abstract classes and base classes for plugins, LLMs, formatters, and data connectors. This indicates a plugin architecture.
– “app/embeddings”, “app/loaders”, “app/plugins”, and “app/vectordb”: These directories implement integrations with external providers (e.g., OpenAI, Cohere, Google) and connect to different data sources or vector databases.
– “app/providers”: Provides middleware, caching, configuration management, and container handling.
– “app/models”, “app/repository”, “app/schemas”, and “app/services”: Manage data models, persistence interactions, and business logic.
- External Services & Infrastructure:
– LLM Inference APIs (OpenAI, Gemini, Claude, and Together.ai) are supported.
– Data connectors and plugins enable integration with structured data sources like databases (MySQL, PostgreSQL, etc.) as well as document-based sources.
– A vector database (for example, Chroma as configured in “config.yaml”) is used to store and query embeddings.
– Zitadel is used for authentication and identity management. The Docker Compose files (e.g., zitadel-docker-compose.yaml) and instructions indicate how to run and configure this external service.
- Utility and Configuration Components:
– Environment setup using configuration files (config.yaml, .env).
– Deployment files: Dockerfile, docker-compose.yml, and Makefile.
– Testing suites in the “tests” directory ensure both functional and integration tests.

##### Establish the Relationships and Interactions
- Backend API as a central component broken into several submodules:
– API endpoints (handling incoming HTTP/S requests).
– Chain modules that process conversational logic by interacting with the various plugins and loaders.
– Plugins and connectors that interface with external data sources (structured and unstructured).
– Embedding and vector database modules for storing/retrieving context.
– From the UI to API endpoints.
– From the API to chain modules where data is processed and routed.
– From chain modules to:
- External LLM providers (for inference calls).
- Data source connectors/plugins (which in turn may connect to databases or document storage).
- Vector DB components (e.g., Chroma or MongoDB) for efficient retrieval.
- Optionally, show a side note for utility modules (configuration reading, JWT utilities, etc.) that support the core functionality.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly show that the frontend (UI) is decoupled from the backend. Also, the backend further separates API routing, business logic (chains and services), and integration layers (plugins, connectors).

##### Relevant Technologies and Frameworks
- Python is used in the backend. Note the use of standard libraries and frameworks (e.g., Flask or FastAPI might be assumed based on the API structure).
- UI is built using React (in combination with Vite) and managed with npm, as seen in the “ui” directory.
- Docker and Docker Compose are used for deployment (Dockerfile, docker-compose.yml, and zitadel-docker-compose.yaml).
- Various third-party libraries: For vector databases (Chroma), embeddings (OpenAI, Cohere, Google), and others.

##### Putting It All Together
- Ancillary components such as configuration files, testing modules, and deployment scripts as supporting elements on the periphery if needed.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface"
        UI("Frontend UI"):::frontend
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        AP("API Endpoints"):::backend
        CC("Conversation Chain Manager"):::chain
        BA("Plugin & Base Classes"):::plugin
        PC("Middleware & Config"):::providers
        DM("Data Models"):::data
        RE("Repository Management"):::data
        SC("Schemas"):::data
        SE("Services"):::data
        EM("Embedding Handlers"):::integration
        DL("Data Loaders"):::integration
        PL("Plugins/Connectors"):::integration
    end

    %% External Services and Data Stores
    subgraph "Data & External Integrations"
        LLM("LLM Inference Service"):::external
        VDB("Vector DB Integration"):::database
        ZI("Zitadel Auth"):::external
        ZDC("Zitadel Docker"):::external
    end

    %% Utility and Deployment Components
    subgraph "Utility & Deployment"
        CFG("Config.yaml"):::util
        ENV(".env.example"):::util
        RC("Read Config Utility"):::util
        DOF("Dockerfile"):::util
        DCOM("docker-compose.yml"):::util
        MF("Makefile"):::util
        TST("Testing Suites"):::util
    end

    %% Data Flow Connections
    UI -->|"REST"| AP
    AP -->|"invoke"| CC
    AP -->|"middleware"| PC
    AP -->|"service"| SE
    PC -->|"auth_flow"| ZI
    CC -->|"LLM_call"| LLM
    CC -->|"plugin_call"| PL
    CC -->|"context_retrieval"| VDB
    CC -->|"load_data"| DL
    CC -->|"get_embedding"| EM
    BA -->|"base_for"| PL
    SE -->|"model_logic"| DM
    SE -->|"repo_logic"| RE
    SE -->|"schema_valid"| SC
    ZI -->|"container_config"| ZDC

    %% Click Events
    click UI "https://github.com/sirocco-ventures/raggenie/tree/main/ui/"
    click AP "https://github.com/sirocco-ventures/raggenie/tree/main/app/api/v1/"
    click CC "https://github.com/sirocco-ventures/raggenie/tree/main/app/chain/"
    click BA "https://github.com/sirocco-ventures/raggenie/tree/main/app/base/"
    click EM "https://github.com/sirocco-ventures/raggenie/tree/main/app/embeddings/"
    click DL "https://github.com/sirocco-ventures/raggenie/tree/main/app/loaders/"
    click PL "https://github.com/sirocco-ventures/raggenie/tree/main/app/plugins/"
    click PC "https://github.com/sirocco-ventures/raggenie/tree/main/app/providers/"
    click DM "https://github.com/sirocco-ventures/raggenie/tree/main/app/models/"
    click RE "https://github.com/sirocco-ventures/raggenie/tree/main/app/repository/"
    click SC "https://github.com/sirocco-ventures/raggenie/tree/main/app/schemas/"
    click SE "https://github.com/sirocco-ventures/raggenie/tree/main/app/services/"
    click VDB "https://github.com/sirocco-ventures/raggenie/tree/main/app/vectordb/"
    click ZI "https://github.com/sirocco-ventures/raggenie/blob/main/app/providers/zitadel.py"
    click ZDC "https://github.com/sirocco-ventures/raggenie/blob/main/zitadel-docker-compose.yaml"
    click CFG "https://github.com/sirocco-ventures/raggenie/blob/main/config.yaml"
    click ENV "https://github.com/sirocco-ventures/raggenie/blob/main/.env.example"
    click RC "https://github.com/sirocco-ventures/raggenie/blob/main/app/utils/read_config.py"
    click DOF "https://github.com/sirocco-ventures/raggenie/tree/main/Dockerfile"
    click DCOM "https://github.com/sirocco-ventures/raggenie/blob/main/docker-compose.yml"
    click MF "https://github.com/sirocco-ventures/raggenie/tree/main/Makefile"
    click TST "https://github.com/sirocco-ventures/raggenie/tree/main/tests/"

    %% Class Definitions with Colors
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef chain fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
    classDef plugin fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef providers fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef integration fill:#B2EBF2,stroke:#00695C,stroke-width:2px;
    classDef data fill:#D1C4E9,stroke:#4527A0,stroke-width:2px;
    classDef database fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef external fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef util fill:#CFD8DC,stroke:#37474F,stroke-width:2px;
```
