# tdguchi/cuestionario architecture

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

- Interactive diagram: https://gitdiagram.com/tdguchi/cuestionario
- Repository: https://github.com/tdguchi/cuestionario

## Overview

Basándonos en el archivo de proyecto y en el README, este sistema de cuestionarios es una aplicación web desarrollada en Flask que permite cargar y gestionar preguntas de exámenes o quizzes mediante archivos JSON. La aplicación utiliza una base de datos SQLite para almacenar las preguntas y sus estados, integra notificaciones a través de Discord Webhook, y está preparada tanto para ejecución directa en un entorno Python como para contenerización mediante Docker y docker-compose.

A continuación, se explica cómo diseñar el diagrama de arquitectura y se indican los elementos clave a incluir:

##### Identificar los componentes principales
- Servidor (Backend): Representado por el archivo app.py, es el núcleo de la aplicación. Aquí se procesan las rutas, se maneja la lógica de negocio y se produce la integración con la base de datos y el webhook de Discord.
- Base de Datos: Se nota la presencia de archivos como banco.db y schema.sql. Esto indica que se utiliza SQLite para gestionar las preguntas y sus respectivos estados.
- Frontend: Se apoya en el sistema de templates (por ejemplo, quiz.html en la carpeta templates) y en los archivos estáticos (carpeta static con CSS y JavaScript) que definen la interfaz de usuario.
- Gestión de Archivos JSON: La carpeta json_prueba contiene archivos de ejemplo que definen la estructura de las preguntas. Este componente es importante, ya que su carga conduce a la creación o actualización de tablas en la base de datos, dependiendo de la asignatura.
- Integración Externa: Discord Webhook configurado en el .env (con las variables DISCORD_WEBHOOK_URL y modo_cooperativo) que envía notificaciones al cargar nuevos archivos.
- Contenedorización y Configuración de Entorno: Archivos Dockerfile, docker-compose.yml, .dockerignore, .env y requirements.txt; que permiten desplegar la aplicación en entornos controlados y reproducibles.

##### Relaciones e Interacciones
- El cliente (navegador) realiza peticiones HTTP al servidor (app.py).
- El servidor renderiza vistas usando las plantillas HTML (presentes en la carpeta templates) y utiliza los archivos estáticos (en la carpeta static) para la presentación.
- El servidor interactúa con la base de datos SQLite (banco.db), siguiendo el esquema definido en schema.sql, para gestionar preguntas, estados y resultados.
- Al subir archivos JSON, se procesa la información para insertar o actualizar datos en la base de datos, y se envía una notificación a través del webhook configurado hacia Discord.
- Docker y docker-compose se encargan de orquestar el despliegue, encapsulando toda la aplicación y sus dependencias.

##### Patrones y Tecnologías identificadas
- Arquitectura tipo MVC simplificada: donde el Modelo es la base de datos, la Vista corresponde a las plantillas HTML y recursos estáticos, y el Controlador se implementa en app.py.
- Uso de contenedores Docker: lo que permite separar el entorno de ejecución y gestionar dependencias.
- Integración con APIs externas (Discord) a través de Webhook.
- Procesamiento y validación de archivos JSON para dinamizar la carga de datos en la base de datos.

##### Instrucciones para el Diagrama
a. Componentes y Etiquetas:
- Etiquete claramente cada uno de los componentes: "Backend (Flask - app.py)", "Base de Datos (SQLite - banco.db, schema.sql)", "Frontend (Templates y Static)", "Carga de JSON (json_prueba)", "Discord Webhook (Integración Externa)", y "Contenerización (Docker, docker-compose)".
b. Relaciones e Interacciones:
- Dibuje flechas direccionales para mostrar el flujo de datos: por ejemplo, desde el "Cliente" (navegador) al "Backend", y desde este a la "Base de Datos" y "Discord Webhook".
- Incluir flechas bidireccionales entre el "Backend" y el "Frontend" explicando la renderización de vistas y recepción de peticiones.
- Mostrar cómo la carga de archivos JSON desencadena acciones en el backend que actualizan la base de datos y envían notificaciones a Discord.
c. Uso de Colores y Formas:
- Distinga los componentes “Backend”, “Frontend”, “Base de Datos” y “Integraciones Externas” usando diferentes colores o formas (por ejemplo, rectángulos para servidores, cilindros para bases de datos, nubes para integraciones).
- Utilice líneas sólidas para conexiones de comunicación interna y líneas punteadas para las integraciones externas (como el webhook de Discord).

##### Ajuste según el tipo de aplicación
- Para este sistema de cuestionarios, resalte la separación entre la lógica de negocio (Flask) y la presentación (templates y archivos estáticos).
- Detalle la interacción de la carga dinámica de JSON, que actualiza la base de datos y activa notificaciones, lo que es esencial para el funcionamiento del cuestionario.
- Indique la importancia del contenedor Docker para un despliegue uniforme y para encapsular todas las dependencias, mejorando la portabilidad de la aplicación.

Con estos elementos, el diagrama de sistema resultante debe proporcionar una vista completa y detallada de la estructura y flujo de información de la aplicación, permitiendo a los equipos técnicos (en este caso, el principal software engineer) entender fácilmente la arquitectura, identificar puntos de integración y realizar mantenimiento o mejoras de manera organizada.

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["Cliente (Navegador)"]:::client
    backend["Backend (Flask - app.py)"]:::backend
    json["Carga de JSON (json_prueba)"]:::json
    discord["Discord Webhook (Integración Externa)"]:::external

    subgraph "Frontend (Templates y Archivos Estáticos)"
        template["Template: quiz.html"]:::frontend
        static["Archivos Estáticos"]:::frontend
    end

    subgraph "Base de Datos (SQLite)"
        banco["banco.db"]:::database
        esquema["schema.sql"]:::database
    end

    subgraph "Contenerización y Entorno"
        docker["Dockerfile"]:::container
        compose["docker-compose.yml"]:::container
        dckignore[".dockerignore"]:::container
        reqs["requirements.txt"]:::container
    end

    %% Relaciones principales
    client -->|"HTTP"| backend
    json -->|"Carga"| backend
    backend <-->|"Renderiza"| template
    backend <-->|"Utiliza"| static
    backend -->|"OperacionesDB"| banco
    backend -->|"OperacionesDB"| esquema
    backend -.->|"Notifica"| discord

    %% Integración de Contenerización (líneas punteadas)
    docker -.-> backend
    docker -.-> template
    docker -.-> static
    docker -.-> discord

    %% Click Events
    click backend "https://github.com/tdguchi/cuestionario/blob/main/app.py"
    click banco "https://github.com/tdguchi/cuestionario/blob/main/banco.db"
    click esquema "https://github.com/tdguchi/cuestionario/blob/main/schema.sql"
    click template "https://github.com/tdguchi/cuestionario/blob/main/templates/quiz.html"
    click static "https://github.com/tdguchi/cuestionario/tree/main/static/"
    click json "https://github.com/tdguchi/cuestionario/tree/main/json_prueba/"
    click discord "https://github.com/tdguchi/cuestionario/blob/main/.env"
    click docker "https://github.com/tdguchi/cuestionario/tree/main/Dockerfile"
    click compose "https://github.com/tdguchi/cuestionario/blob/main/docker-compose.yml"
    click dckignore "https://github.com/tdguchi/cuestionario/blob/main/.dockerignore"
    click reqs "https://github.com/tdguchi/cuestionario/blob/main/requirements.txt"

    %% Estilos
    classDef client fill:#ffeb99,stroke:#f39c12,stroke-width:2px;
    classDef backend fill:#a9d0f5,stroke:#333,stroke-width:2px;
    classDef frontend fill:#f7a8b8,stroke:#333,stroke-width:2px;
    classDef database fill:#adebad,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef container fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef json fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
