# if-7100-2025/preguntas-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/if-7100-2025/preguntas-frontend
- Repository: https://github.com/if-7100-2025/preguntas-frontend

## Overview

Para diseñar un diagrama de arquitectura preciso de la “Plataforma de Aprendizaje Interactiva” (frontend React/Vite), sigue estos pasos:

##### Detectar el tipo de sistema y su propósito
- Es una aplicación web de frontend (React + TypeScript + Vite) que consume APIs de un backend (no incluido en el repo).
- Ofrece: publicación y categorización de preguntas (manual / IA), generación de quizzes, manejo de usuarios (auth/roles).

##### Analizar la estructura de archivos
- **src/pages/**: vistas principales (home, login, register, quiz, history, moderation, profile, myQuestions, verificationCode, welcome).
- **src/components/**: UI reusable (sidebar, animatedPage, notification, preguntaForm, quicesForm).
- **src/services/**: capa de acceso a APIs (http.service, auth.service, quiz.service, question.service, moderation.service, profile.service, home.service, cookies.service).
- **src/hooks/**: lógica compartida (useApiHandlers, useSessionHandler, notificationHandler; store con Zustand).
- **src/contexts/**: contextos React (ThemeContext y UserContext).
- **assets, models, styles**: recursos estáticos, definición de interfaces/modelos, CSS global/local.

##### Extraer del README
- Stack: React/TypeScript + Vite, ESLint, Zustand para estado global.
- Funcionalidad clave: interacción cliente→servidor, IA externa para categorización.

##### Componentes principales a incluir
a. **Cliente Web (Browser/React App)**
- Subcomponentes:
- Views (pages)
- Component Library (components)
- Contextos React (ThemeContext, UserContext)
- Estado global (Zustand stores)
- Custom Hooks
- Herramientas de construcción: Vite
b. **Capa de Servicios (HTTP/API Layer)**
- http.service.ts (configura peticiones)
- auth.service.ts, quiz.service.ts, question.service.ts, etc.
- cookies.service.ts (persistencia de token/credenciales)
c. **Backend / API Gateway** (externo; no está en este repo)
- Endpoints REST: /auth, /questions, /quizzes, /moderation, /profile, /home, etc.
- Microservicio IA (podría ser un endpoint de terceros o interno)
d. **Almacenamiento y Persistencia**
- Base de datos relacional o NoSQL (suponer en backend)
e. **Servicios externos**
- Servicio IA para categorización de preguntas
- Servicio de notificaciones (si aplica)

##### Relaciones e interacciones
- El **Frontend** usa los **Custom Hooks** y el **Store** para trigger de acciones.
- Estas llamadas van a la **Capa de Servicios** → HTTP client → **API Backend**.
- El Backend puede invocar el **Servicio IA** para procesar y devolver categorías.
- El estado del usuario (auth, roles) se mantiene en **cookies** + **UserContext**.
- UI reacciona a cambios de estado vía React Contexts / Zustand.
- Notificaciones del sistema se manejan en **NotificationListener** y el hook notificationHandler.

##### Patrones y principios arquitectónicos
- **Separación de responsabilidades**: Distinto folder para UI (components, pages), lógica de acceso a datos (services), estado (store), contextos y hooks.
- **Container/Presentational**: Pages orquestan lógica, Components solo render.
- **Unidirectional Data Flow**: React → Hooks/Store → Services → API → Store → React.
- **Composable**: custom hooks + contexts reutilizables.

##### Guía para dibujar el diagrama
- Usa **rectángulos** o **cajas** para cada componente principal (Frontend, Hooks/Stores, Services, Backend API, IA Service, Database).
- Añade **flechas direccionales**:
- User Interaction → React Pages/Components
- Components → Hooks/Store → Services → HTTP Client → Backend API
- Backend API → IA Service → Backend API
- Backend API → Database
- Auth Service ↔ cookies.service ↔ UserContext
- **Colores o formas** distintas:
- Azul: Frontend (Pages, Components, Contexts, Stores)
- Verde: Services / HTTP Layer
- Naranja: Backends externos (API, IA, DB)
- **Etiquetas** claras sobre cada flecha (p. ej. “GET /questions”, “POST /quiz”, “Categorizar pregunta”).

##### Consejos finales
- Sé detallado en cada subcomponente relevante (ej. listar stores, servicios).
- No sobrecargues: agrupa elementos de la misma capa en un único contenedor con subdivisiones internas.
- Documenta supuestos (por ejemplo: tipo de base de datos, endpoints principales).
- Mantén consistencia en colores y estilos en todo el diagrama.

Con estos elementos, tu diagrama mostrará con claridad la arquitectura de la aplicación frontend, cómo se comunican los distintos módulos internos y cómo éstos encajan con el backend y servicios externos de IA.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client Web (React App)" 
        direction TB
        main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        vite["vite.config.ts"]:::frontend
        index["index.html"]:::frontend
    end

    subgraph "Views (Pages)" 
        Pages["src/pages"]:::frontend
    end

    subgraph "Component Library (UI Reusable)" 
        Components["src/components"]:::frontend
    end

    subgraph "Contextos React"
        ThemeCtx["ThemeContext.tsx"]:::frontend
        UserCtx["UserContext.tsx"]:::frontend
    end

    subgraph "Estado Global (Zustand Stores)"
        SessionStore["session.store.ts"]:::frontend
        NotificationStore["notification.store.ts"]:::frontend
    end

    subgraph "Custom Hooks"
        useApi["useApiHandlers.ts"]:::frontend
        useSession["useSessionHandler.ts"]:::frontend
        notifHandler["notificationHandler.ts"]:::frontend
        useAppStore["useAppStore.ts"]:::frontend
    end

    %% Services Layer
    subgraph "Capa de Servicios (HTTP/API Layer)" 
        direction TB
        HTTP["http.service.ts"]:::services
        Auth["auth.service.ts"]:::services
        Cookies["cookies.service.ts"]:::services
        QuizSvc["quiz.service.ts"]:::services
        QuestionSvc["question.service.ts"]:::services
        ModSvc["moderation.service.ts"]:::services
        ProfileSvc["profile.service.ts"]:::services
        HomeSvc["home.service.ts"]:::services
    end

    %% Backend / External Services
    subgraph "Backend API & Externos"
        direction TB
        API["Backend API"]:::external
        IA["IA Service"]:::external
        DB["Database"]:::external
    end

    %% Relationships
    %% Entry
    index --> main
    main --> App
    App --> Pages
    App --> Components
    App --> ThemeCtx
    App --> UserCtx

    %% Pages interactions
    Pages --> useApi
    Pages --> useSession
    Pages --> notifHandler
    Pages --> useAppStore
    Pages --> Components
    Pages --> SessionStore
    Pages --> NotificationStore

    %% Hooks and Stores call services
    useApi --> HTTP
    useSession --> Auth
    useSession --> Cookies
    useAppStore --> HTTP
    notifHandler --> HTTP
    SessionStore --> Cookies
    NotificationStore --> HTTP

    %% Services to Backend
    HTTP -->|GET/POST| API
    Auth -->|POST /auth| API
    QuizSvc -->|POST /quizzes| API
    QuestionSvc -->|GET /questions| API
    ModSvc -->|POST /moderation| API
    ProfileSvc -->|GET/PUT /profile| API
    HomeSvc -->|GET /home| API

    %% Backend flows
    API -->|invoke| IA
    IA -->|response| API
    API -->|read/write| DB

    %% Auth-Cookies-Context linkage
    Auth -- Stores token --> Cookies
    Cookies -- Provides creds --> UserCtx

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef services fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#FF8F00,color:#E65100

    %% Click Events
    click main "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/main.tsx"
    click App "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/App.tsx"
    click vite "https://github.com/if-7100-2025/preguntas-frontend/blob/main/vite.config.ts"
    click index "https://github.com/if-7100-2025/preguntas-frontend/blob/main/index.html"
    click Pages "https://github.com/if-7100-2025/preguntas-frontend/tree/main/src/pages"
    click Components "https://github.com/if-7100-2025/preguntas-frontend/tree/main/src/components"
    click ThemeCtx "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/contexts/ThemeContext.tsx"
    click UserCtx "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/contexts/UserContext.tsx"
    click SessionStore "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/store/session.store.ts"
    click NotificationStore "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/store/notification.store.ts"
    click useApi "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/useApiHandlers.ts"
    click useSession "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/useSessionHandler.ts"
    click notifHandler "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/notificationHandler.ts"
    click useAppStore "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/hooks/useAppStore.ts"
    click HTTP "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/http.service.ts"
    click Auth "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/auth.service.ts"
    click Cookies "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/cookies.service.ts"
    click QuizSvc "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/quiz.service.ts"
    click QuestionSvc "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/question.service.ts"
    click ModSvc "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/moderation.service.ts"
    click ProfileSvc "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/profile.service.ts"
    click HomeSvc "https://github.com/if-7100-2025/preguntas-frontend/blob/main/src/services/home.service.ts"
```
