# rwth-acis/lms-chatbot-service architecture

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

- Interactive diagram: https://gitdiagram.com/rwth-acis/lms-chatbot-service
- Repository: https://github.com/rwth-acis/lms-chatbot-service

## Overview

##### Project Type and Purpose
- This is a specialized backend “LMS-chatbot service” (MoodleBot) that uses generative AI frameworks (LangChain, LLamaIndex) to answer student questions and act as a tutor. It integrates with an external Social Bot Framework and a Moodle instance, and persists data to Weaviate (vector DB) and MongoDB.

##### File Structure Analysis
- Top-level entrypoints:
- app.py – service bootstrap / HTTP or messaging endpoint
- agents.py, questionGenerator.py, factchecker.py – encapsulate different LangChain agent behaviors
- indexRetriever.py, weaviateRetriever.py – document retrieval logic
- bot/…Model.json – pre-trained or fine-tuned chatbot model definitions
- Config & deployment:
- Dockerfile, docker-compose.yaml, .github/workflows/docker-CI.yml – containerization & CI
- requirements.txt – Python dependencies (LangChain, LLamaIndex, weaviate-client, OpenAI SDK)
- Tests under tests/ validate ingestion, PDF handling, prompts, etc.

##### Key README Insights
- Core tech stack: OpenAI API, LLamaIndex, LangChain, Weaviate, MongoDB
- External integrations: Social Bot Framework, tech4comp Moodle
- Environment variables drive endpoints for Weaviate, Mongo, credentials, selected file paths

##### Main Components
A. User Interface Layer
- Social Bot Framework → MoodleBot service (app.py)
B. API / Orchestration Layer
- app.py routes incoming requests to appropriate agent in agents.py
C. Retrieval Layer
- indexRetriever.py / weaviateRetriever.py → query Weaviate vector store
D. Indexing and Vector Store
- Weaviate cluster (Vector DB)
E. LLM Agent Layer
- LangChain / LLamaIndex agents (agents.py, questionGenerator.py, factchecker.py) calling OpenAI API
F. Persistence Layer
- MongoDB (chat history collection)
- Optional: local file paths or slide ingestion logic
G. Infrastructure / DevOps
- Docker containers (service, weaviate, mongo) orchestrated by docker-compose
- CI pipeline (.github/workflows)

##### Relationships and Data Flows
1. User → Social Bot Framework → HTTP/gRPC → MoodleBot app
2. app.py → Routing → Retrieval Layer → Weaviate
3. Retrieved docs → Agent Layer → OpenAI API → Agent response
4. Agent response → app.py → Social Bot Framework → User
5. app.py logs request/response → MongoDB
- During ingestion: File system (slides, PDFs) → indexRetriever → Weaviate ingestion

##### Architectural Patterns and Principles
- Modular “plugin” pattern for different agents (tutor, fact-checker, question generator)
- Separation of concerns: retrieval vs. generative logic vs. persistence vs. integration
- Containerized microservices (each component in docker-compose)
- Use of environment variables for external service endpoints and credentials

##### Essential Elements
- Clear component labels (e.g., “app.py (FastAPI/Gunicorn)”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        User["User"]:::external
        BotFramework["Social Bot Framework"]:::external
        Moodle["Moodle LMS"]:::external
    end

    subgraph "Service Container"
        direction TB
        App["app.py (FastAPI/Gunicorn)"]:::internal
        Agents["agents.py"]:::internal
        QGen["questionGenerator.py"]:::internal
        Fact["factchecker.py"]:::internal
        IndexRet["indexRetriever.py"]:::internal
        WeavRet["weaviateRetriever.py"]:::internal
        BotModel1["LMSBotModel.json"]:::internal
        BotModel2["LMSBotModelNew.json"]:::internal
    end

    subgraph "Data Stores"
        direction TB
        Weaviate["Weaviate (Vector DB)"]:::datastore
        Mongo["MongoDB"]:::datastore
    end

    OpenAI["OpenAI API"]:::cloud

    subgraph "DevOps & CI/CD"
        Dockerfile["Dockerfile"]:::devops
        Compose["docker-compose.yaml"]:::devops
        CI[".github/workflows/docker-CI.yml"]:::devops
        Req["requirements.txt"]:::devops
        TestsDir["tests/"]:::devops
    end

    User -->|"via Social Bot Framework"| BotFramework
    BotFramework -->|"HTTP/gRPC"| App
    App -->|"route to agents"| Agents
    Agents -->|"invokes"| QGen
    Agents -->|"invokes"| Fact
    App -->|"load model definitions"| BotModel1
    App -->|"load model definitions"| BotModel2
    App -->|"retrieve docs"| IndexRet
    IndexRet -->|"uses client"| WeavRet
    WeavRet -->|"query (ENV: WEAVIATE_URL)"| Weaviate
    Weaviate -->|"documents"| IndexRet
    IndexRet -->|"provides docs"| Agents
    Agents -->|"OpenAI request"| OpenAI
    OpenAI -->|"response"| Agents
    Agents -->|"deliver response"| App
    App -->|"response to user"| BotFramework
    App -->|"log chat (ENV: MONGO_CONNECTION_STRING)"| Mongo

    Compose -->|"defines containers"| App
    Compose -->|"defines containers"| Weaviate
    Compose -->|"defines containers"| Mongo
    Dockerfile -->|"builds service image"| App
    CI -->|"runs pipeline"| Compose
    Req -->|"installs deps"| App
    TestsDir -->|"validated in CI"| CI

    click App "https://github.com/rwth-acis/lms-chatbot-service/blob/main/app.py"
    click Agents "https://github.com/rwth-acis/lms-chatbot-service/blob/main/agents.py"
    click QGen "https://github.com/rwth-acis/lms-chatbot-service/blob/main/questionGenerator.py"
    click Fact "https://github.com/rwth-acis/lms-chatbot-service/blob/main/factchecker.py"
    click IndexRet "https://github.com/rwth-acis/lms-chatbot-service/blob/main/indexRetriever.py"
    click WeavRet "https://github.com/rwth-acis/lms-chatbot-service/blob/main/weaviateRetriever.py"
    click Compose "https://github.com/rwth-acis/lms-chatbot-service/blob/main/docker-compose.yaml"
    click BotModel1 "https://github.com/rwth-acis/lms-chatbot-service/blob/main/bot/LMSBotModel.json"
    click BotModel2 "https://github.com/rwth-acis/lms-chatbot-service/blob/main/bot/LMSBotModelNew.json"
    click Dockerfile "https://github.com/rwth-acis/lms-chatbot-service/tree/main/Dockerfile"
    click CI "https://github.com/rwth-acis/lms-chatbot-service/blob/main/.github/workflows/docker-CI.yml"
    click Req "https://github.com/rwth-acis/lms-chatbot-service/blob/main/requirements.txt"
    click TestsDir "https://github.com/rwth-acis/lms-chatbot-service/tree/main/tests/"

    classDef internal fill:#AEDFF7,stroke:#036;
    classDef external fill:#E0E0E0,stroke:#666;
    classDef datastore fill:#C6F6D5,stroke:#256029;
    classDef cloud fill:#FFF1A8,stroke:#DAC000;
    classDef devops fill:#F0E68C,stroke:#C2B280;
```
