# leonxrdon/botnology architecture

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

- Interactive diagram: https://gitdiagram.com/leonxrdon/botnology
- Repository: https://github.com/leonxrdon/botnology

## Overview

Para guiar al ingeniero principal en la creación del diagrama de arquitectura de **Botnology**, sigue estos pasos y recomendaciones, adaptadas al proyecto real:

##### Identificación del tipo de proyecto y propósito
- Es una aplicación full‑stack basada en **Django** que gestiona catálogos de productos en PDF.
- Incluye un frontend web (templates y JS), un backend REST/views, ingestión asíncrona de PDFs con **Celery**, y un chatbot que usa **Azure OpenAI**.
- Se integra con **Azure Document Intelligence** para extraer datos de los PDFs y almacena todo en una base de datos relacional.

##### Análisis de la estructura de archivos
- Carpeta raíz:
- botnology/: configuración de Django (ASGI, WSGI, settings, URLs, celery.py)
- process/: lógica de extracción de PDFs (models, tasks, gpt.py, utils)
- store/: lógica de catálogo y chatbot (models, views, templates, chat.py)
- media/: PDFs subidos
- staticfiles/ y store/static/: recursos CSS/JS/JSON para UI
- db.sqlite3 y migrations: persistencia relacional
- Configuración de Celery en botnology/celery.py
- Dependencias en requirements.txt (Django, Celery, Azure SDKs, etc.)

##### Puntos clave del README
- Arquitectura bimodal:
a. Servicio de extracción de datos (Azure Document Intelligence + Celery)
b. Aplicación Django + Chatbot (Azure OpenAI)
- Uso de Celery para procesar PDFs en segundo plano y evitar bloqueos.
- Interacción síncrona del usuario vía web UI y chatbot.

##### Cómo dibujar el diagrama de sistema
a. Componentes principales
- Cliente Web (Navegador con HTML/JS/CSS)
- Servidor Django (Gunicorn/ASGI)
- Base de datos relacional (SQLite en desarrollo; PostgreSQL en producción)
- Almacenamiento de medios (sistema de ficheros o blob storage)
- Broker de mensajería (Redis o RabbitMQ para Celery)
- Workers de Celery
- Azure Document Intelligence (Servicio externo)
- Azure OpenAI (Servicio externo GPT-4o-mini)
- CDN o servidor de staticfiles (opcional)

b. Relaciones e interacciones
1. El usuario sube un PDF → Django recibe en `store.views` y lo guarda en `media/pdfs`.
2. Django encola tarea Celery (process.tasks) vía broker.
3. Worker Celery consume la tarea → llama al servicio Azure Document Intelligence (API REST), extrae metadatos y contenido.
4. Worker almacena resultados en la base de datos (`process.models.UploadedPDF`, `store.models.Product`).
5. Usuario consulta catálogo vía frontend → Django lee de la base de datos y sirve páginas HTML (store/templates).
6. Usuario chatea → petición AJAX al endpoint de chatbot (store.chat or process.gpt) → Django llama a Azure OpenAI → formatea la respuesta con enlaces a productos → devuelve JSON al cliente.

c. Patrones arquitectónicos
- **Separación de responsabilidades**: Apps “process” (ingestión asíncrona) vs. “store” (presentación y chatbot).
- **Colas de tareas**: Celery para desacoplar ingestión de PDFs.
- **Backend-for-Frontend**: Django expone endpoints que sirven tanto HTML como JSON.
- **Servicios externos**: Azure Document Intelligence y Azure OpenAI encapsulados detrás de clases utilitarias (`process/utils.py`, `process/gpt.py`, `store/chat.py`).

d. Tecnologías / librerías clave
- Django 4.2 (ORM, views, templates, admin)
- Celery (process/tasks.py)
- Azure SDKs (document-intelligence, openai)
- Python (async/await en ASGI)
- JS/CSS en `staticfiles` y `store/static`

##### Directrices para el diagrama (full‑stack Django)
- Delimita claramente:
- Capa UI (client-side)
- Capa Web/API (Django)
- Capa de Persistencia (DB + Media)
- Capa de Procesamiento asíncrono (Celery + Broker)
- Servicios externos (Azure)
- Muestra flujos de datos:
- Síncrono (peticiones HTTP/HTTPS)
- Asíncrono (colas de mensajes)
- Destaca:
- Endpoints REST/Views de Django
- Tasks de Celery
- Puntos de integración con Azure

##### Elementos gráficos recomendados
- Forma:
- Rectángulos para componentes internos
- Cilindros para bases de datos
- Nubes para servicios externos (Azure)
- Paralelogramos para almacenamiento de archivos
- Flechas direccionales etiquetadas (“HTTP POST PDF”, “enqueue task”, “API call”, “DB write/read”)
- Código de colores (ejemplo):
- Azul para servidor Django y apps
- Naranja para Celery y broker
- Verde para servicios Azure
- Gris para almacenamiento local
- Leyenda con símbolos y colores

##### Consejos finales
- Sé exhaustivo: cada carpeta/app es un componente potencial.
- Etiqueta claramente los puertos (8000, broker 6379, etc.) si aplica.
- Muestra los flujos de error o retry de Celery si lo consideras crítico.
- Incluye anotaciones sobre escalabilidad (ej. auto‑scale workers, uso de blob storage en producción).

Con estos lineamientos, el diagrama reflejará fielmente la arquitectura de Botnology, su separación de capas, flujos de datos y la interacción con los servicios de Azure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        Browser["Web Client (HTML/JS/CSS)"]:::ui
    end

    %% Web/API Layer
    subgraph "Web/API Layer"
        Manage["manage.py"]:::django
        DJConfig["Django Core Config"]:::django
        ASGI["ASGI/Gunicorn"]:::django
        subgraph "Process App"
            ProcModels["process/models.py"]:::django
            ProcViews["process/views.py"]:::django
            ProcTasks["process/tasks.py"]:::celery
            ProcGPT["process/gpt.py"]:::django
            ProcUtils["process/utils.py"]:::django
            ProcAdmin["process/admin.py"]:::django
        end
        subgraph "Store App"
            StoreModels["store/models.py"]:::django
            StoreViews["store/views.py"]:::django
            StoreURLs["store/urls.py"]:::django
            StoreChat["store/chat.py"]:::django
            StoreUtils["store/utils.py"]:::django
            StoreTemplates["store/templates/*.html"]:::django
            StoreAdmin["store/admin.py"]:::django
        end
        Req["requirements.txt"]:::django
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB["Relational DB (SQLite/PostgreSQL)"]:::storage
        Media["Media Storage (media/pdfs)"]:::storage
        StaticGlob["Global Static (staticfiles)"]:::storage
        StaticStore["Store Static (store/static/)"]:::storage
    end

    %% Async Processing
    subgraph "Async Processing"
        Broker["Message Broker (Redis/RabbitMQ)"]:::celery
        Worker["Celery Worker"]:::celery
    end

    %% External Services
    subgraph "External Services"
        DocInt["Azure Document Intelligence"]:::azure
        OpenAI["Azure OpenAI"]:::azure
    end

    %% Connections - UI to Web/API
    Browser -->|"HTTP GET/POST"| ASGI
    Browser -->|"AJAX Chat Request"| StoreChat

    %% Web/API internals
    ASGI --> DJConfig
    ASGI --> Manage
    ASGI --> ProcViews
    ASGI --> StoreViews

    %% Store app flows
    StoreViews -->|"Save PDF"| Media
    StoreViews -->|"Enqueue Task"| Broker
    StoreViews -->|"Read/Write"| DB
    StoreViews -->|"Serve Static"| StaticStore
    ASGI --> StaticGlob

    %% Process app flows
    ProcViews -->|"Maybe Sync Endpoints"| Media
    ProcTasks -->|"Call API"| DocInt
    ProcTasks -->|"Write Results"| DB
    ProcTasks --> ProcGPT
    ProcTasks --> ProcUtils
    ProcViews --> ProcModels

    %% Async Processing flows
    Broker -->|"Deliver Task"| Worker
    Worker --> ProcTasks

    %% Chat flows
    StoreChat -->|"API Call"| OpenAI
    OpenAI -->|"Response JSON"| StoreChat
    StoreChat -->|"Read Products"| DB

    %% Storage and static
    ASGI --> StaticGlob

    %% Click Events
    click DJConfig "https://github.com/leonxrdon/botnology/blob/main/botnology/settings.py"
    click Manage "https://github.com/leonxrdon/botnology/blob/main/manage.py"
    click Req "https://github.com/leonxrdon/botnology/blob/main/requirements.txt"
    click DB "https://github.com/leonxrdon/botnology/blob/main/db.sqlite3"
    click Media "https://github.com/leonxrdon/botnology/tree/main/media/pdfs/"
    click StaticGlob "https://github.com/leonxrdon/botnology/tree/main/staticfiles/"
    click StaticStore "https://github.com/leonxrdon/botnology/tree/main/store/static/"
    click ProcModels "https://github.com/leonxrdon/botnology/blob/main/process/models.py"
    click ProcViews "https://github.com/leonxrdon/botnology/blob/main/process/views.py"
    click ProcTasks "https://github.com/leonxrdon/botnology/blob/main/process/tasks.py"
    click ProcGPT "https://github.com/leonxrdon/botnology/blob/main/process/gpt.py"
    click ProcUtils "https://github.com/leonxrdon/botnology/blob/main/process/utils.py"
    click ProcAdmin "https://github.com/leonxrdon/botnology/blob/main/process/admin.py"
    click StoreModels "https://github.com/leonxrdon/botnology/blob/main/store/models.py"
    click StoreViews "https://github.com/leonxrdon/botnology/blob/main/store/views.py"
    click StoreURLs "https://github.com/leonxrdon/botnology/blob/main/store/urls.py"
    click StoreChat "https://github.com/leonxrdon/botnology/blob/main/store/chat.py"
    click StoreUtils "https://github.com/leonxrdon/botnology/blob/main/store/utils.py"
    click StoreTemplates "https://github.com/leonxrdon/botnology/tree/main/store/templates/"
    click StoreAdmin "https://github.com/leonxrdon/botnology/blob/main/store/admin.py"

    %% Styles
    classDef ui fill:#D6EFFF,stroke:#000;
    classDef django fill:#CCE5FF,stroke:#000;
    classDef celery fill:#FFD8B1,stroke:#000;
    classDef azure fill:#C8E6C9,stroke:#000;
    classDef storage fill:#F0F0F0,stroke:#000;
```
