# ruben-quilez/maxi_bot architecture

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

- Interactive diagram: https://gitdiagram.com/ruben-quilez/maxi_bot
- Repository: https://github.com/ruben-quilez/maxi_bot

## Overview

A continuación se muestra una guía detallada para diseñar un diagrama de arquitectura que capture con precisión la estructura y flujo de datos de este sistema RAG. La idea es representar de manera clara y detallada los componentes principales y sus interacciones, utilizando formas, colores y direccionalidad que hagan evidente el flujo de información y las dependencias. La explicación se adapta específicamente al proyecto presentado.

##### Proyecto y propósito
- Tipo de proyecto: Este es un sistema de Retrieval Augmented Generation (RAG) que combina la generación de embeddings/respuestas mediante OpenAI y la búsqueda/almacenamiento en Qdrant, una base de datos vectorial.
- Propósito: Realizar consultas de preguntas, buscar respuestas relevantes en un dataset previamente cargado en Qdrant, y generar respuestas contextuales usando modelos de OpenAI.

##### Principales componentes del sistema
a. API / Backend:
- Ubicado en la carpeta “app”. Implementado con FastAPI (implicado en la definición de endpoints en endpoints.py, configuración en config.py y lógica en main.py y utils.py).
- Realiza la orquestación del flujo: recibe solicitudes, consulta Qdrant, obtiene embeddings de OpenAI y genera respuestas.
- Contenedor Docker definido con el Dockerfile (en app/Dockerfile) y administrado mediante Docker Compose.

b. Qdrant:
- Base de datos vectorial para almacenar y recuperar datos (ubicado en el directorio “qdrant” con subdirectorios para configuración y datos).
- Se despliega como servicio (contenedor) definido en docker-compose.yml.

c. Dataset y Script de carga:
- Archivo dataset.json como fuente de datos de preguntas y respuestas.
- El script “scripts/load_dataset.py” es el encargado de cargar estos datos en Qdrant. Se utiliza en la inicialización mediante el script init_service.sh.

d. Integración con OpenAI:
- Utilizado para generar embeddings y respuestas; la configuración se maneja en las variables de entorno (.env, en env.example) y a través del código en la aplicación (config.py, endpoints.py, etc.).
- Especificación de modelos (como text-embedding-3-large y gpt-4o-mini-2024-07-18).

##### Relaciones e interacciones
- El cliente (por ejemplo, a través de Swagger UI) realiza solicitudes HTTP a la API.
- La API procesa peticiones:
- Extrae y procesa la consulta.
- Realiza búsquedas en Qdrant para obtener datos relevantes basados en embeddings.
- Llama a la API de OpenAI para generar respuestas a partir de los prompts predefinidos (ubicados en “app/static/prompts”).
- El script de inicialización (init_service.sh) facilita la configuración del entorno, creación del entorno virtual, verificación de la existencia del dataset y carga inicial de datos en Qdrant.
- Docker Compose se utiliza para levantar conjuntamente los servicios de la API FastAPI y Qdrant, manteniendo la conexión vía QDRANT_HOST (ya sea "maxi_qdrant" en Docker o "localhost" en ejecución local).

##### Recomendaciones para el diagrama
- Componentes visuales:
- Dibujar bloques para cada uno de los principales módulos:
1. Cliente/Interfaz de Usuario (Swagger UI/Redoc o terminal).
2. API FastAPI (Backend).
3. Servicio OpenAI (externo, indicado como servicio de terceros).
4. Base de Datos Qdrant (vectorial).
5. Dataset y Scripts de inicialización.
- Incluir contenedores Docker para la API y Qdrant, representando el entorno de despliegue.
- Mostrar la dependencia de configuración (archivo .env y variables clave que se usan en la aplicación).
- Conexiones y flujo de datos:
- Utilizar flechas direccionales para mostrar:
- Flujo de solicitudes entrantes desde el Cliente a la API.
- La llamada de la API al servicio de OpenAI.
- La consulta y actualización de datos entre la API y Qdrant.
- Indicar en las flechas los protocolos o tipos de petición, por ejemplo, HTTP o API REST.
- Detalles técnicos:
- Etiquetar cada bloque con su función (p.ej., “API REST (FastAPI)”, “Base de Datos Qdrant”, “Servicio de OpenAI”).
- Usar colores distintos para diferenciar componentes internos (backend, base de datos) versus servicios externos.
- Incluir un bloque extra para el “Script de Inicialización / Carga de Dataset”, indicando su función en el proceso de configuración.

##### Pautas de detalle para un diagrama específico a este proyecto
- Asegurarse de dividir claramente entre backend (API) y base de datos (Qdrant). Aun siendo una aplicación de backend, enfatizar la integración con un servicio externo (OpenAI) que juega un papel crítico.
- Incluir las capas de infraestructura: contenedores Docker (Dockerfile en app, docker-compose.yml) y el proceso de inicialización (init_service.sh) que automatiza la configuración.
- Representar el flujo de datos en el proceso de Query: Desde la solicitud del usuario, generación de embeddings, consulta en Qdrant, hasta la respuesta generada.
- Destacar en el diagrama la interacción dual entre el sistema (por ejemplo, la misma API que maneja endpoints para consulta y adición de Q&A).

##### Elementos gráficos
- Etiquetas claras en cada componente.
- Flechas direccionadas para ilustrar el flujo de datos e interacciones.
- Uso de colores o formas (por ejemplo, rectángulos, cilindros para bases de datos) para distinguir entre servicios, bases de datos, componentes de terceros y scripts de administración.

Siguiendo estos lineamientos, se obtendrá un diagrama de arquitectura completo y ajustado a las necesidades del proyecto. Esto no solo ayudará a clarificar la estructura del sistema, sino que también facilitará la comunicación entre los equipos de desarrollo y operaciones, permitiendo entender rápidamente cómo se integran OpenAI, Qdrant y la API FastAPI en una solución RAG robusta y escalable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Cliente
    subgraph "Cliente"
        client["Cliente (Swagger UI/Terminal)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        api["API REST (FastAPI)"]:::backend
        subgraph "Módulos Internos"
            m1["Aplicación Principal"]:::backend
            m2["Definición de Endpoints"]:::backend
            m3["Configuración y OpenAI Integration"]:::backend
            m4["Utilidades"]:::backend
        end
        e["Variables de Entorno"]:::backend
        p["Prompts"]:::backend
        dapi["Docker Container (API)"]:::docker
    end

    %% Servicios Externos e Infraestructura
    subgraph "Servicios Externos e Infraestructura"
        dc["Docker Compose"]:::docker
        db["Base de Datos Qdrant"]:::database
        oai["Servicio OpenAI"]:::external
    end

    %% Inicialización y Datos
    subgraph "Inicialización y Datos"
        ds["Dataset (dataset.json)"]:::script
        scriptLoad["Script de Carga"]:::script
        initService["Script de Inicialización"]:::script
    end

    %% Conexiones de flujo de datos e interacciones
    client -->|"HTTP"| api
    api -->|"Consulta"| db
    api -->|"LlamadaAPI"| oai
    api --> m1
    api --> m2
    api --> m3
    api --> m4
    e -->|"config"| m3
    m3 -->|"usa"| p
    dc --> dapi
    dc --> db
    scriptLoad --> initService
    initService -->|"Cargadat"| db

    %% Estilos
    classDef client fill:#ffdead,stroke:#000,stroke-width:1px;
    classDef backend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef docker fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef database fill:#f4a460,stroke:#000,stroke-width:1px;
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef script fill:#e6e6fa,stroke:#000,stroke-width:1px;

    %% Click Events
    click m1 "https://github.com/ruben-quilez/maxi_bot/blob/main/app/main.py"
    click m2 "https://github.com/ruben-quilez/maxi_bot/blob/main/app/endpoints.py"
    click m3 "https://github.com/ruben-quilez/maxi_bot/blob/main/app/config.py"
    click m4 "https://github.com/ruben-quilez/maxi_bot/blob/main/app/utils.py"
    click dapi "https://github.com/ruben-quilez/maxi_bot/tree/main/app/Dockerfile"
    click dc "https://github.com/ruben-quilez/maxi_bot/blob/main/docker-compose.yml"
    click ds "https://github.com/ruben-quilez/maxi_bot/blob/main/dataset.json"
    click scriptLoad "https://github.com/ruben-quilez/maxi_bot/blob/main/scripts/load_dataset.py"
    click initService "https://github.com/ruben-quilez/maxi_bot/blob/main/init_service.sh"
    click p "https://github.com/ruben-quilez/maxi_bot/tree/main/app/static/prompts/"
    click e "https://github.com/ruben-quilez/maxi_bot/blob/main/env.example"
```
