# urjcdslab/vilt architecture

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

- Interactive diagram: https://gitdiagram.com/urjcdslab/vilt
- Repository: https://github.com/urjcdslab/vilt

## Overview

##### Project Type and Purpose
- ViLT is a full-stack tutoring platform designed for virtual tutoring at ETSII (URJC). It helps teachers upload material (PDFs) for processing and indexing (using ChromaDB) while students query the system. The platform uses advanced NLP techniques, language models (Llama 3.1, OpenAI), LangChain, and retrieval augmented generation (RAG) techniques.
- This project not only handles content management (uploading, indexing, document processing) but also orchestrates dynamic conversation flows and feedback loops to fine-tune responses.

##### Main Architectural Components
a. Frontend / User Interface:
- Templates: HTML files in the “templates” folder for various user roles (admin, teacher, student, chatbot interfaces).
- Static Assets: CSS, JS, and image resources in “static” which style and manage user interactions.
b. Backend Application Layer:
- The “vilt” directory contains core modules. These include:
- app.py: Entry-point for the application.
- Module managers such as chatbotmanager, careermanager, dashmanager, databasemanager, docmanager, embeddingmanager, infomanager, keywordsmanager, promptmanager, timemanager, and usermanager. Each one encapsulates a specific domain (e.g., user management, chatbot logic, document processing).
- The “bbdd-management” folder contains scripts dedicated to database tasks (creation, deletion, CSV management) which indicate structured external processes for handling data.
c. Data and External Content:
- “data-external” contains external CSVs (for careers, student lists, and syllabi) that appear to be raw data sources ingested into the system.
d. Document and Content Processing:
- PDF uploads from professors are processed in the workflow (document manager likely manages parsing and indexing documents). The “docs” folder itself and the external test folders for processed documents indicate that documentation and content processing is a key part.
e. Integration with External Services:
- The system requires connections to MongoDB (database layer).
- It integrates with external language model APIs (OpenAI, OLLAMA) and uses LangChain for query processing.
- ChromaDB is used for fast document indexing and retrieval.
f. Testing:
- The “testes” folder provides test scripts for key functionalities such as database operations, chatbot training, dash management, and data processing—indicating robust testing practices.

##### Relationships and Data Flow
- Users (teachers and students) interact through the web interface (rendered via templates and static assets).
- For content ingestion:
- Teachers upload PDFs → routed to the docmanager (and embeddings creation/deletion modules) → content is indexed into ChromaDB.
- Query and tutoring workflow:
- Students submit queries → routed through chatbotmanager where incoming queries are processed; LangChain and language models (Llama, OpenAI) are used to fetch the best response.
- Feedback is collected (through templates for feedback) and stored via the databasemanager.
- Database Handling:
- The database management scripts and the databasemanager module interact with MongoDB to store and retrieve necessary data (user information, content metadata, feedback).
- Management dashboards and administrative modules (admin-add, admin-modify templates, etc.) indicate separation of functionality based on roles.

##### Architectural Patterns and Design Principles
- Modular decomposition: Each core functionality (chatbot operations, document management, user administration) is encapsulated in its own module.
- Separation of concerns: Clear separation between presentation (frontend), business logic (managers in the “vilt” folder), and data handling (database management and external CSV ingestion).
- Data flow directions: Clarify how data flows from user requests → backend processing modules → database or external APIs, and then responses back to the user.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        USERS("Users (Teachers/Students)"):::user
        TEMPLATES("Templates (HTML)"):::ui
        STATIC("Static Assets (CSS,JS)"):::ui
    end

    %% Backend Application Layer
    subgraph "Backend Application Layer"
        APP("Application Entry (app.py)"):::backend
        CHAT("Chatbot Manager"):::backend
        DOC("Document Manager"):::backend
        DBMAN("Database Manager"):::backend
        CAREER("Career Manager"):::backend
        DASH("Dashboard Manager"):::backend
        EMBED("Embedding Manager"):::backend
        INFO("Information Manager"):::backend
        KEYWORDS("Keywords Manager"):::backend
        PROMPT("Prompt Manager"):::backend
        TIME("Time Manager"):::backend
        USERMAN("User Manager"):::backend
    end

    %% Data & External Integration Layer
    subgraph "Data & External Integration Layer"
        DBSCRIPTS("Database Scripts"):::external
        CSV("External CSV Data"):::external
        MONGO("MongoDB"):::external
        CHROMA("ChromaDB"):::external
        LANGCHAIN("LangChain"):::external
        LM("Language Models (OpenAI,Llama)"):::external
        PROMPTS_EXT("Prompts (Language Model Prompts)"):::external
    end

    %% Content & Document Processing Layer
    subgraph "Content & Document Processing"
        DOCS("Docs Folder"):::doc
        DOC_TEST("Document Test Files"):::doc
    end

    %% Testing Components
    subgraph "Testing Components"
        TEST("Test Scripts"):::test
    end

    %% Connections between layers
    %% User Interface to Backend
    USERS --> TEMPLATES
    USERS --> STATIC
    TEMPLATES --> APP
    STATIC --> APP

    %% Backend Module interactions
    APP --> CHAT
    APP --> DOC
    APP --> DBMAN
    APP --> CAREER
    APP --> DASH
    APP --> EMBED
    APP --> INFO
    APP --> KEYWORDS
    APP --> PROMPT
    APP --> TIME
    APP --> USERMAN

    %% Document Upload and Processing Flow
    TEMPLATES -- "uploadPDF" --> DOC
    DOC -- "processPDF" --> EMBED
    EMBED -- "indexDoc" --> CHROMA
    DOC -- "referenceDocs" --> DOCS

    %% Chatbot Query Flow
    TEMPLATES -- "submitQuery" --> CHAT
    CHAT -- "invokeLangChain" --> LANGCHAIN
    LANGCHAIN -- "callModel" --> LM
    CHAT -- "logQuery" --> DBMAN
    DBMAN -- "storeData" --> MONGO

    %% Database and External Data Interactions
    DBMAN -- "performOps" --> DBSCRIPTS
    CSV --> DBSCRIPTS

    %% Additional Backend Interactions
    CAREER -- "updateCareerInfo" --> DBMAN
    DASH -- "displayDash" --> DBMAN
    INFO -- "retrieveInfo" --> DBMAN
    KEYWORDS -- "manageKeywords" --> DBMAN
    USERMAN -- "userDataOps" --> DBMAN

    %% Prompts Integration
    PROMPT -- "loadPrompts" --> PROMPTS_EXT

    %% Testing connection to App
    TEST -- "validateModules" --> APP

    %% Click Events
    click TEMPLATES "https://github.com/urjcdslab/vilt/tree/main/templates/"
    click STATIC "https://github.com/urjcdslab/vilt/tree/main/static/"
    click APP "https://github.com/urjcdslab/vilt/blob/main/vilt/app.py"
    click CHAT "https://github.com/urjcdslab/vilt/blob/main/vilt/chatbotmanager.py"
    click DOC "https://github.com/urjcdslab/vilt/blob/main/vilt/docmanager.py"
    click DBMAN "https://github.com/urjcdslab/vilt/blob/main/vilt/databasemanager.py"
    click CAREER "https://github.com/urjcdslab/vilt/blob/main/vilt/careermanager.py"
    click DASH "https://github.com/urjcdslab/vilt/blob/main/vilt/dashmanager.py"
    click EMBED "https://github.com/urjcdslab/vilt/blob/main/vilt/embeddingmanager.py"
    click INFO "https://github.com/urjcdslab/vilt/blob/main/vilt/infomanager.py"
    click KEYWORDS "https://github.com/urjcdslab/vilt/blob/main/vilt/keywordsmanager.py"
    click PROMPT "https://github.com/urjcdslab/vilt/blob/main/vilt/promptmanager.py"
    click TIME "https://github.com/urjcdslab/vilt/blob/main/vilt/timemanager.py"
    click USERMAN "https://github.com/urjcdslab/vilt/blob/main/vilt/usermanager.py"
    click DBSCRIPTS "https://github.com/urjcdslab/vilt/tree/main/bbdd-management/"
    click CSV "https://github.com/urjcdslab/vilt/tree/main/data-external/"
    click DOCS "https://github.com/urjcdslab/vilt/tree/main/docs/"
    click DOC_TEST "https://github.com/urjcdslab/vilt/tree/main/testes/processed_docs/"
    click TEST "https://github.com/urjcdslab/vilt/tree/main/testes/"
    click PROMPTS_EXT "https://github.com/urjcdslab/vilt/tree/main/prompts/"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#7b1fa2,stroke-width:2px;
    classDef doc fill:#fff59d,stroke:#f9a825,stroke-width:2px;
    classDef test fill:#ffe082,stroke:#ffb300,stroke-width:2px;
    classDef user fill:#ffcc80,stroke:#fb8c00,stroke-width:2px;
```
