# javitrucas/chatbot_ia_ceprud architecture

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

- Interactive diagram: https://gitdiagram.com/javitrucas/chatbot_ia_ceprud
- Repository: https://github.com/javitrucas/chatbot_ia_ceprud

## Overview

##### Identificación del tipo de proyecto y su propósito
- Se trata de un **chatbot basado en IA** para CEPRUD, implementado como una aplicación full-stack ligera.
- Combina un **frontend web** (HTML/CSS/JS), una **API REST en Python** y un **motor RAG** (Retrieval-Augmented Generation) con fine-tuning QLoRA para generar respuestas.
- Incluye además pipelines de **preprocesamiento**, **generación de embeddings**, **población de base de datos**, **entrenamiento** y **visualización de métricas**.

##### Análisis de la estructura de ficheros
- Top-level scripts:
- `app.py`, `api.py`: punto de entrada del backend y definición de endpoints REST.
- `generate_data.py`, `get_embedding_function.py`, `populate_database.py`: pipeline de datos para RAG.
- `finetuning_qlora.py`, `finetuned-model_test.py`: fine-tuning y tests de QLoRA.
- `script_graphs.py`: generación de gráficos de métricas.
- Directorios claves:
- `data/`: corpus de documentos y JSON de entrenamiento.
- `models/`: modelos base, adaptadores QLoRA y checkpoints.
- `templates/`, `static/`: frontend web (HTML, CSS).
- `logs/`, `graphs/`: almacenamiento de logs de chat y gráficos generados.
- Tests automáticos en archivos `test_*.py`.

##### Insights del README
- Usa RAG con embeddings + recuperación de documentos.
- La API REST es ligera y sirve el chatbot a través de `app.py` y `api.py`.
- Soporta fine-tuning con QLoRA para dominios específicos.
- Ofrece un demo frontend básico y generación de logs/métricas.

##### Componentes principales a representar en el diagrama
a. Frontend web:
- Navegador ▶ plantillas HTML (`templates/index.html`) + CSS/JS (`static/`).
b. Backend/API:
- `app.py` (servidor web, Flask/FastAPI)
- `api.py` (endpoints RAG: `/chat`, `/metrics`, etc.)
- `query_logic.py` (lógica que orquesta embedding, recuperación e inferencia).
c. Pipeline de datos y RAG:
- `generate_data.py` → limpieza/transformación de datos.
- `get_embedding_function.py` → función de generación de embeddings.
- `populate_database.py` → construcción de base de datos vectorial.
d. Base de datos de vectores y documentos:
- Almacenamiento local o servicio embebido para RAG.
e. Motor de inferencia:
- Modelos QLoRA en `models/...-deepseek-qlora`
- Llamada al LLM base (p.ej. Hugging Face) + adaptador QLoRA.
f. Módulo de fine-tuning:
- `finetuning_qlora.py` y checkpoints en `models/.../checkpoint-*`.
g. Logs y métricas:
- `logs/chat_logs.csv` + gráficos generados por `script_graphs.py`, almacenados en `graphs/`.

##### Relación e interacción entre componentes
- Flujo de usuario:
Usuario ▶ Frontend ▶ HTTP POST `/chat` ▶ Backend/API ▶ `query_logic.py`
├─> Embedding ▶ Base vectorial (RAG) ▶ documentos
└─> Llamada a LLM adaptado (QLoRA) ▶ respuesta
▶ API devuelve JSON al Frontend ▶ se muestra en la interfaz.
- Flujo de datos y training:
`generate_data.py` ▶ datos limpios ▶ `get_embedding_function.py` ▶ embeddings
▶ `populate_database.py` ▶ base vectorial
▶ `finetuning_qlora.py` ▶ nuevos modelos en `models/` ▶ tests con `finetuned-model_test.py`.
- Flujo de métricas:
Logs de chat (CSV) ▶ `script_graphs.py` ▶ gráficos en `graphs/`.

##### Patrones y principios arquitectónicos
- **Separación de capas**: UI / API / lógica de negocio / persistencia de vectores / modelos ML.
- **Pipeline ETL** para ingestión y recuperación de datos.
- **Microservicio ligero** (API REST) para desacoplar frontend y backend de ML.
- **Diseño modular**: scripts y módulos independientes por responsabilidad.

##### Guía para dibujar el diagrama
- Utilizar **cajas** (rectángulos) para cada componente: Frontend, API, Lógica RAG, Vector DB, Model Store, ETL, Logs/Métricas.
- **Flechas direccionales**:
- Flujo de usuario (Front ▶ API ▶ RAG ▶ Modelos ▶ API ▶ Front).
- Flujo de datos (ETL ▶ Vector DB).
- Flujo de entrenamiento (Data ▶ Fine-tuning ▶ Model Store).
- Flujo de generación de métricas (Logs ▶ Script Graphs ▶ Graphs).
- **Colores** o formas distintas:
- Azul para componentes web/API.
- Verde para pipelines de datos/RAG.
- Naranja para modelos ML.
- Gris para almacenamiento (logs, base de datos, gráficos).
- Etiquetar claramente cada flecha con la acción o el tipo de dato que transporta (por ejemplo, “embedding request”, “vector lookup”, “chat response”).

##### Recomendaciones finales
- Mantener el diagrama **limpio** y **legible**, agrupando componentes relacionados.
- Numerar o usar **leyenda** si hay muchos subprocesos (ETL, training, inference).
- Verificar que todos los scripts y directorios del proyecto estén representados según su rol.
- Revisar la **dirección** de las flechas para que el flujo sea intuitivo de izquierda a derecha o de arriba a abajo.

Con estas indicaciones, se obtiene un diagrama detallado y organizado, adaptado al proyecto Chatbot_IA_Ceprud, donde las flechas muestran claramente el flujo de datos y las interacciones entre frontend, backend, pipeline RAG y módulos de ML.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Capa Frontend" 
        style FrontendBg fill:#E8F4FD,stroke:#0366D6,stroke-width:1px
        Navegador["Usuario\n(Navegador)"]:::frontend
        Index["templates/index.html"]:::frontend
        Static["static/assets CSS/JS"]:::frontend
    end

    %% Backend/API
    subgraph "Capa API/Backend"
        style BackendBg fill:#E8F4FD,stroke:#0366D6,stroke-width:1px
        App["app.py"]:::api
        API["api.py"]:::api
        Logic["query_logic.py"]:::api
    end

    %% RAG Pipeline
    subgraph "Pipeline de Datos y RAG"
        style PipelineBg fill:#E6F5E1,stroke:#2E8B57,stroke-width:1px
        GenData["generate_data.py"]:::pipeline
        EmbFunc["get_embedding_function.py"]:::pipeline
        PopDB["populate_database.py"]:::pipeline
        VectorDB["Base de datos vectorial"]:::storage
    end

    %% Motor e Inferencia
    subgraph "Modelos e Inferencia"
        style ModelBg fill:#FFF4E5,stroke:#D2691E,stroke-width:1px
        QLoRA1["models/ingenieria del conocimiento-deepseek-qlora/"]:::model
        QLoRA2["models/metaheuristicas-deepseek-qlora/"]:::model
        QLoRA3["models/modelos_avanzados_computacion-deepseek-qlora/"]:::model
        FineTune["finetuning_qlora.py"]:::model
        TestFT["finetuned-model_test.py"]:::model
        LLM["LLM base + adaptador QLoRA"]:::model
    end

    %% Logs y Métricas
    subgraph "Logs y Métricas"
        style LogsBg fill:#F2F2F2,stroke:#666666,stroke-width:1px
        ChatLogs["logs/chat_logs.csv"]:::storage
        GraphScript["script_graphs.py"]:::storage
        Graphs["graphs/"]:::storage
    end

    %% Tests
    subgraph "Pruebas Automatizadas"
        style TestBg fill:#F9F0FF,stroke:#8A2BE2,stroke-width:1px
        TestEmb["test_rag_embeddings.py"]:::test
        TestAPI["test_server.py"]:::test
    end

    %% Flujo de usuario
    Navegador -->|"Carga página"| Index
    Index --> Static
    Navegador -->|"Envía solicitud chat"| App
    App --> API
    API -->|"POST /chat"| Logic
    Logic -->|"Solicitud embedding"| EmbFunc
    EmbFunc -->|"Embedding"| VectorDB
    Logic -->|"Vector lookup"| VectorDB
    VectorDB -->|"Documentos relevantes"| Logic
    Logic -->|"Inferencia QLoRA"| LLM
    LLM -->|"Respuesta generada"| Logic
    Logic --> API
    API -->|"JSON respuesta"| Navegador

    %% Flujo ETL/RAG
    GenData -->|"Datos limpios"| EmbFunc
    EmbFunc -->|"Embeddings"| PopDB
    PopDB -->|"Puebla"| VectorDB

    %% Flujo de entrenamiento
    GenData -->|"Datos entrenamiento"| FineTune
    FineTune -->|"Checkpoints"| QLoRA1
    FineTune --> QLoRA2
    FineTune --> QLoRA3
    QLoRA1 --> TestFT
    QLoRA2 --> TestFT
    QLoRA3 --> TestFT

    %% Flujo de métricas
    ChatLogs --> GraphScript
    GraphScript --> Graphs

    %% Pruebas
    TestEmb --> EmbFunc
    TestAPI --> API

    %% Click Events
    click Index "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/templates/index.html"
    click Static "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/static/styles.css"
    click App "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/app.py"
    click API "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/api.py"
    click Logic "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/query_logic.py"
    click GenData "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/generate_data.py"
    click EmbFunc "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/get_embedding_function.py"
    click PopDB "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/populate_database.py"
    click PopDB "https://github.com/javitrucas/chatbot_ia_ceprud/tree/main/data/"
    click FineTune "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/finetuning_qlora.py"
    click TestFT "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/finetuned-model_test.py"
    click QLoRA1 "https://github.com/javitrucas/chatbot_ia_ceprud/tree/main/models/ingenieria del conocimiento-deepseek-qlora/"
    click QLoRA2 "https://github.com/javitrucas/chatbot_ia_ceprud/tree/main/models/metaheuristicas-deepseek-qlora/"
    click QLoRA3 "https://github.com/javitrucas/chatbot_ia_ceprud/tree/main/models/modelos_avanzados_computacion-deepseek-qlora/"
    click ChatLogs "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/logs/chat_logs.csv"
    click GraphScript "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/script_graphs.py"
    click Graphs "https://github.com/javitrucas/chatbot_ia_ceprud/tree/main/graphs/"
    click TestEmb "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/test_rag_embeddings.py"
    click TestAPI "https://github.com/javitrucas/chatbot_ia_ceprud/blob/main/test_server.py"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366D6,stroke-width:1px
    classDef api fill:#D0E7FF,stroke:#0366D6,stroke-width:1px
    classDef pipeline fill:#DFF0D8,stroke:#2E8B57,stroke-width:1px
    classDef storage fill:#ECECEC,stroke:#666666,stroke-width:1px
    classDef model fill:#FFE7C4,stroke:#D2691E,stroke-width:1px
    classDef test fill:#F3E5FF,stroke:#8A2BE2,stroke-width:1px
```
