# khairu-aqsara/moodle-blocks_terusrag architecture

> Architecture diagram of the GitHub repository khairu-aqsara/moodle-blocks_terusrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khairu-aqsara/moodle-blocks_terusrag
- Repository: https://github.com/khairu-aqsara/moodle-blocks_terusrag

## Overview

##### Project Type and Purpose
- This is a Moodle block plugin named “Terus RAG” that implements Retrieval-Augmented Generation (RAG) to allow users to query course content via large language models.
- It indexes course descriptions, summaries, and other content into a vector store (Moodle DB by default) and uses BM25 + cosine similarity for retrieval.

##### File Structure
- Top-level plugin files:
- block_terusrag.php (entry point)
- version.php, settings.php, lang/, templates/, styles.css, edit_form.php (Moodle block scaffolding)
- classes/ – core PHP classes:
- provider_interface.php – defines LLM provider abstraction
- gemini.php, openai.php, ollama.php – provider implementations
- bm25.php – ranking algorithm
- llm.php – shared vector operations
- task/datainitializer.php – scheduled task for indexing
- db/ – Moodle database schema and upgrade/install scripts
- amd/ – front-end JavaScript (raginterface.js) for interactive UI
- tests/ – PHPUnit tests for provider integrations
- utils/ – stopwords list

##### Review README Insights
- Explains integrations with three AI providers and their embedding pathways.
- Describes daily scheduled tasks and manual CLI execution.

##### Main Components
a. Content Layer
– Moodle Course Content (descriptions, summaries, activities)
– Content Extractor & Text Chunker (PHP task)
b. Embedding Layer
– AI Provider Adapter (interface + implementations)
– Embedding Models (Gemini, OpenAI, Ollama)
– Vector Storage (Moodle DB by default; optional ChromaDB/Supabase)
c. Query Layer
– UI Input (block rails + AMD JS)
– Query Processor & Embedding Generation
– Vector Search (BM25 + cosine similarity)
d. Response Layer
– Context Assembly
– AI Provider Chat API Calls
– Response Formatter & UI Display

##### Relationships and Data Flows
- From User Query → Front-end JS → Query Processor → Embedding Adapter → Vector Search → Retrieved Chunks → Context Assembly → AI Provider Chat API → Formatter → UI.
- Scheduled task flows separately from real-time query flows.

##### Architectural Patterns
- Layered architecture (four layers as above).
- Adapter pattern for AI providers (provider_interface + implementations).
- Hybrid retrieval pattern (BM25 + vector similarity).
- Plugin structure following Moodle block conventions.

##### Technologies, Frameworks, Libraries
- PHP 7.4+, Moodle 4.1+ plugin APIs
- JavaScript AMD module (raginterface.js)
- PHPUnit for testing
- External AI APIs: Gemini, OpenAI, Ollama

##### Final Advice
- Be very detailed: break down the scheduled task into sub-steps (scan, chunk, embed, store).
- Adapter Pattern for AI providers: one interface feeding multiple provider implementations.
- Hybrid ranking: BM25 + vector similarity as parallel retrieval paths merging into candidate selection.
- Don’t over-complicate: keep four main layers, then expand each into logical subcomponents.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        direction TB
        CC["Moodle Course Content"]:::content
        Scheduled["Scheduled Task (DataInitializer)"]:::content
        CE["Content Extractor & Text Chunker"]:::content
    end

    %% Embedding Layer
    subgraph "Embedding Layer"
        direction TB
        PI["AI Provider Adapter Interface"]:::embedding
        subgraph "Provider Implementations"
            direction TB
            Gem["Gemini Embedding/Chat Provider"]:::embedding
            OAI["OpenAI Embedding/Chat Provider"]:::embedding
            Oll["Ollama Embedding/Chat Provider"]:::embedding
        end
        BMR["Hybrid Retrieval – BM25 Ranking"]:::embedding
        VecOps["Vector Operations & Cosine Similarity"]:::embedding
        subgraph "Vector Stores"
            direction TB
            Store["Moodle DB Vector Store"]:::embedding
            Chroma["ChromaDB (Optional)"]:::embedding
            Supa["Supabase (Optional)"]:::embedding
        end
    end

    %% Query Layer
    subgraph "Query Layer"
        direction TB
        UI["UI Input (AMD JS)"]:::query
        QP["Query Processor & Embedding Generation"]:::query
        VS["Vector Search"]:::query
    end

    %% Response Layer
    subgraph "Response Layer"
        direction TB
        CA["Context Assembly"]:::response
        APICall["AI Provider Chat API Calls"]:::response
        RF["Response Formatter & UI Display"]:::response
    end

    %% Scheduled Indexing Flow
    CC -->|Scan Content| Scheduled
    Scheduled -->|Extract & Chunk| CE
    CE -->|Send to Adapter| PI
    PI -->|Embed| Gem
    PI -->|Embed| OAI
    PI -->|Embed| Oll
    Gem -->|Embedding Vectors| VecOps
    OAI -->|Embedding Vectors| VecOps
    Oll -->|Embedding Vectors| VecOps
    VecOps -->|Store Vectors| Store
    VecOps -->|Store Vectors| Chroma
    VecOps -->|Store Vectors| Supa

    %% Real-Time Query Flow
    UI -->|User Query| QP
    QP -->|Generate Embedding| PI
    PI -->|Embed Query| Gem
    PI -->|Embed Query| OAI
    PI -->|Embed Query| Oll
    Gem -->|Query Vectors| VecOps
    OAI -->|Query Vectors| VecOps
    Oll -->|Query Vectors| VecOps
    VecOps -->|Vectors & BM25| VS
    QP -->|BM25 Scores| BMR
    BMR -->|Scores| VS
    VS -->|Top Chunks| CA
    CA -->|Context| APICall
    APICall -->|LLM Response| RF
    RF -->|Display| UI

    %% Click Events
    click CE "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/task/datainitializer.php"
    click Scheduled "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/db/tasks.php"
    click BMR "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/bm25.php"
    click VecOps "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/llm.php"
    click PI "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/provider_interface.php"
    click Gem "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/gemini.php"
    click OAI "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/openai.php"
    click Oll "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/classes/ollama.php"
    click Store "https://github.com/khairu-aqsara/moodle-blocks_terusrag/blob/main/db/install.xml"

    %% Styles
    classDef content fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef embedding fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef query fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef response fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef external fill:#CFD8DC,stroke:#455A64,color:#000
```
