# donathaniel/qr-technovation-uv architecture

> Architecture diagram of the GitHub repository donathaniel/qr-technovation-uv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/donathaniel/qr-technovation-uv
- Repository: https://github.com/donathaniel/qr-technovation-uv

## Overview

Sistema web para administrar temporadas, estudiantes, equipos y asistencia estudiantil mediante QR, con roles diferenciados y actualizaciones en tiempo real. El flujo principal es iniciar sesión y elegir temporada, escanear el QR, registrar entrada o salida y consultar el panel o informe. El backend persiste los registros y aplica lógica de asistencia; además, el producto incluye importación, asistencia de mentores, protección de datos sensibles y notificaciones por correo. El mapa refleja relaciones visibles en excerpts, referencias del índice y README; algunos enlaces de rutas y tiempo real no se pudieron verificar en código.

Main entry points: [`frontend/src/App.tsx`](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/App.tsx) (Rutas de la app), [`frontend/src/services/api.ts`](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/services/api.ts) (Cliente API), [`backend/src/database/data-source.js`](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/database/data-source.js) (Acceso a datos), [`backend/src/controllers/studentController.js`](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/studentController.js) (Lógica estudiantes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Aplicación web"]
  node_app["Rutas de la app<br/>[App.tsx]"]
  node_api["Cliente API<br/>[api.ts]"]
  node_scanner["Escáner QR<br/>[QrScanner.tsx]"]
  node_socket["Actualización tiempo real<br/>[useSocket.ts]"]
end

subgraph group_identity["Acceso y temporadas"]
  node_authui["Sesión y temporada<br/>[AuthContext.tsx]"]
  node_login["Servicio de acceso<br/>[auth.ts]"]
  node_seasonui["Gestión temporadas<br/>[SeasonsPage.tsx]"]
  node_seasonaccess["Acceso por temporada<br/>[seasonAccess.js]"]
end

subgraph group_operations["Gestión y asistencia"]
  node_studentsui["Gestión estudiantes<br/>[StudentsPage.tsx]"]
  node_teamsui["Gestión equipos<br/>[TeamsPage.tsx]"]
  node_attendanceui["Panel e informes"]
  node_datesui["Fechas de asistencia<br/>[DatesPage.tsx]"]
  node_importui["Importación estudiantes"]
  node_mentorui["Asistencia mentores"]
  node_teamattendanceui["Asistencia de equipo"]
  node_attendance["Registro de asistencia"]
  node_students["Lógica estudiantes"]
  node_teams["Lógica equipos<br/>[teamController.js]"]
  node_studentimport["Carga de estudiantes"]
  node_mentorattendance["Registro mentores"]
  node_qr["Generación QR<br/>[qrService.js]"]
end

subgraph group_platform["Servicios y persistencia"]
  node_server["Servidor HTTP<br/>[main.js]"]
  node_routes["Rutas API<br/>[auth.js]"]
  node_database[("Acceso a datos<br/>[data-source.js]")]
  node_sensitive["Protección de datos"]
end

subgraph group_messaging["Notificaciones"]
  node_mailqueue["Cola y auditoría email"]
  node_mail["Entrega de correo<br/>[emailService.js]"]
end

node_user(("Mentor o coordinador"))
node_emailprovider["Proveedor de correo"]
node_sockethub["Canal Socket.io"]

node_user -->|"usa"| node_app
node_app -->|"provee sesión"| node_authui
node_app -->|"dirige a"| node_studentsui
node_app -->|"dirige a"| node_teamsui
node_app -->|"dirige a"| node_attendanceui
node_app -->|"dirige a"| node_seasonui
node_app -->|"dirige a"| node_datesui
node_app -->|"dirige a"| node_mentorui
node_authui -->|"invoca"| node_login
node_studentsui -->|"consulta"| node_api
node_teamsui -->|"consulta"| node_api
node_attendanceui -->|"consulta"| node_api
node_attendanceui -->|"suscribe"| node_socket
node_scanner -->|"envía registro"| node_api
node_importui -.->|"envía carga"| node_api
node_teamattendanceui -.->|"consulta"| node_api
node_api -.->|"solicita API"| node_server
node_server -->|"monta rutas"| node_routes
node_server -->|"inicializa"| node_database
node_server -->|"inicia worker"| node_mailqueue
node_routes -.->|"despacha"| node_attendance
node_attendance -->|"lee y escribe"| node_database
node_attendance -->|"protege datos"| node_sensitive
node_students -->|"lee y escribe"| node_database
node_students -->|"genera QR"| node_qr
node_students -->|"encola correo"| node_mailqueue
node_students -->|"protege datos"| node_sensitive
node_studentimport -->|"lee y escribe"| node_database
node_studentimport -->|"protege datos"| node_sensitive
node_teams -->|"lee y escribe"| node_database
node_teams -->|"valida acceso"| node_seasonaccess
node_mentorattendance -->|"lee y escribe"| node_database
node_mentorattendance -->|"valida acceso"| node_seasonaccess
node_mentorattendance -->|"protege datos"| node_sensitive
node_mailqueue -->|"registra trabajos"| node_database
node_mailqueue -->|"entrega correo"| node_mail
node_mail -->|"envía mensaje"| node_emailprovider
node_socket -.->|"recibe eventos"| node_sockethub

click node_app "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/context/AuthContext.tsx"
click node_login "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/services/auth.ts"
click node_api "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/services/api.ts"
click node_scanner "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/components/QrScanner.tsx"
click node_studentsui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/StudentsPage.tsx"
click node_teamsui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/TeamsPage.tsx"
click node_attendanceui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/AttendanceReportPage.tsx"
click node_seasonui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/SeasonsPage.tsx"
click node_datesui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/DatesPage.tsx"
click node_importui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/StudentImportPage.tsx"
click node_mentorui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/MentorAttendancePage.tsx"
click node_teamattendanceui "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/MyTeamAttendancePage.tsx"
click node_socket "https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/hooks/useSocket.ts"
click node_server "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/main.js"
click node_routes "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/routes/auth.js"
click node_attendance "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/attendanceController.js"
click node_students "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/studentController.js"
click node_teams "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/teamController.js"
click node_studentimport "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/studentImportController.js"
click node_mentorattendance "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/mentorAttendanceController.js"
click node_database "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/database/data-source.js"
click node_seasonaccess "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/utils/seasonAccess.js"
click node_sensitive "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/sensitiveDataService.js"
click node_qr "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/qrService.js"
click node_mailqueue "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/emailQueueService.js"
click node_mail "https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/emailService.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_api,node_scanner,node_socket toneBlue
class node_authui,node_login,node_seasonui,node_seasonaccess toneAmber
class node_studentsui,node_teamsui,node_attendanceui,node_datesui,node_importui,node_mentorui,node_teamattendanceui,node_attendance,node_students,node_teams,node_studentimport,node_mentorattendance,node_qr toneMint
class node_server,node_routes,node_database,node_sensitive toneRose
class node_mailqueue,node_mail,node_user,node_emailprovider,node_sockethub toneIndigo
```

## Components

### Aplicación web

- [Rutas de la app](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Cliente API](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Escáner QR](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/components/QrScanner.tsx): `frontend/src/components/QrScanner.tsx`
- [Actualización tiempo real](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/hooks/useSocket.ts): `frontend/src/hooks/useSocket.ts`

### Acceso y temporadas

- [Sesión y temporada](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Servicio de acceso](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/services/auth.ts): `frontend/src/services/auth.ts`
- [Gestión temporadas](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/SeasonsPage.tsx): `frontend/src/pages/SeasonsPage.tsx`
- [Acceso por temporada](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/utils/seasonAccess.js): `backend/src/utils/seasonAccess.js`

### Gestión y asistencia

- [Gestión estudiantes](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/StudentsPage.tsx): `frontend/src/pages/StudentsPage.tsx`
- [Gestión equipos](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/TeamsPage.tsx): `frontend/src/pages/TeamsPage.tsx`
- [Panel e informes](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/AttendanceReportPage.tsx): `frontend/src/pages/AttendanceReportPage.tsx`
- [Fechas de asistencia](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/DatesPage.tsx): `frontend/src/pages/DatesPage.tsx`
- [Importación estudiantes](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/StudentImportPage.tsx): `frontend/src/pages/StudentImportPage.tsx`
- [Asistencia mentores](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/MentorAttendancePage.tsx): `frontend/src/pages/MentorAttendancePage.tsx`
- [Asistencia de equipo](https://github.com/donathaniel/qr-technovation-uv/blob/main/frontend/src/pages/MyTeamAttendancePage.tsx): `frontend/src/pages/MyTeamAttendancePage.tsx`
- [Registro de asistencia](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/attendanceController.js): `backend/src/controllers/attendanceController.js`
- [Lógica estudiantes](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/studentController.js): `backend/src/controllers/studentController.js`
- [Lógica equipos](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/teamController.js): `backend/src/controllers/teamController.js`
- [Carga de estudiantes](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/studentImportController.js): `backend/src/controllers/studentImportController.js`
- [Registro mentores](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/controllers/mentorAttendanceController.js): `backend/src/controllers/mentorAttendanceController.js`
- [Generación QR](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/qrService.js): `backend/src/services/qrService.js`

### Servicios y persistencia

- [Servidor HTTP](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/main.js): `backend/src/main.js`
- [Rutas API](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Acceso a datos](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/database/data-source.js): `backend/src/database/data-source.js`
- [Protección de datos](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/sensitiveDataService.js): `backend/src/services/sensitiveDataService.js`

### Notificaciones

- [Cola y auditoría email](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/emailQueueService.js): `backend/src/services/emailQueueService.js`
- [Entrega de correo](https://github.com/donathaniel/qr-technovation-uv/blob/main/backend/src/services/emailService.js): `backend/src/services/emailService.js`

### Other components

- **Mentor o coordinador**
- **Proveedor de correo**
- **Canal Socket.io**

## Connections

- Mentor o coordinador → Rutas de la app: usa (evidence: `README.md`)
- Rutas de la app → Sesión y temporada: provee sesión (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Gestión estudiantes: dirige a (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Gestión equipos: dirige a (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Panel e informes: dirige a (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Gestión temporadas: dirige a (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Fechas de asistencia: dirige a (evidence: `frontend/src/App.tsx`)
- Rutas de la app → Asistencia mentores: dirige a (evidence: `frontend/src/App.tsx`)
- Sesión y temporada → Servicio de acceso: invoca (evidence: `frontend/src/context/AuthContext.tsx`)
- Gestión estudiantes → Cliente API: consulta (evidence: `frontend/src/pages/StudentsPage.tsx`)
- Gestión equipos → Cliente API: consulta (evidence: `frontend/src/pages/TeamsPage.tsx`)
- Panel e informes → Cliente API: consulta (evidence: `frontend/src/pages/AttendanceReportPage.tsx`)
- Panel e informes → Actualización tiempo real: suscribe (evidence: `frontend/src/pages/AttendanceReportPage.tsx`)
- Escáner QR → Cliente API: envía registro (evidence: `frontend/src/components/QrScanner.tsx`)
- Importación estudiantes → Cliente API: envía carga
- Asistencia de equipo → Cliente API: consulta
- Cliente API → Servidor HTTP: solicita API
- Servidor HTTP → Rutas API: monta rutas (evidence: `backend/src/main.js`)
- Servidor HTTP → Acceso a datos: inicializa (evidence: `backend/src/main.js`)
- Servidor HTTP → Cola y auditoría email: inicia worker (evidence: `backend/src/main.js`)
- Rutas API → Registro de asistencia: despacha
- Registro de asistencia → Acceso a datos: lee y escribe (evidence: `backend/src/controllers/attendanceController.js`)
- Registro de asistencia → Protección de datos: protege datos (evidence: `backend/src/controllers/attendanceController.js`)
- Lógica estudiantes → Acceso a datos: lee y escribe (evidence: `backend/src/controllers/studentController.js`)
- Lógica estudiantes → Generación QR: genera QR (evidence: `backend/src/controllers/studentController.js`)
- Lógica estudiantes → Cola y auditoría email: encola correo (evidence: `backend/src/controllers/studentController.js`)
- Lógica estudiantes → Protección de datos: protege datos (evidence: `backend/src/controllers/studentController.js`)
- Carga de estudiantes → Acceso a datos: lee y escribe (evidence: `backend/src/controllers/studentImportController.js`)
- Carga de estudiantes → Protección de datos: protege datos (evidence: `backend/src/controllers/studentImportController.js`)
- Lógica equipos → Acceso a datos: lee y escribe (evidence: `backend/src/controllers/teamController.js`)
- Lógica equipos → Acceso por temporada: valida acceso (evidence: `backend/src/controllers/teamController.js`)
- Registro mentores → Acceso a datos: lee y escribe (evidence: `backend/src/controllers/mentorAttendanceController.js`)
- Registro mentores → Acceso por temporada: valida acceso (evidence: `backend/src/controllers/mentorAttendanceController.js`)
- Registro mentores → Protección de datos: protege datos (evidence: `backend/src/controllers/mentorAttendanceController.js`)
- Cola y auditoría email → Acceso a datos: registra trabajos (evidence: `backend/src/services/emailQueueService.js`)
- Cola y auditoría email → Entrega de correo: entrega correo (evidence: `backend/src/services/emailQueueService.js`)
- Entrega de correo → Proveedor de correo: envía mensaje (evidence: `backend/src/services/emailService.js`)
- Actualización tiempo real → Canal Socket.io: recibe eventos
