1. Introducción

Este manual técnico proporciona la documentación completa del sistema CEMI, incluyendo su arquitectura, tecnologías utilizadas, estructura del código, configuración de la base de datos, endpoints de la API y procedimientos de despliegue.

2. Stack Tecnológico

Dependencias Principales (package.json)

{
  "dependencies": {
    "express": "^4.18.2",
    "mysql2": "^3.6.0",
    "bcrypt": "^5.1.1",
    "cors": "^2.8.5",
    "dotenv": "^16.3.1",
    "helmet": "^7.0.0",
    "express-rate-limit": "^6.10.0",
    "socket.io": "^4.7.2",
    "morgan": "^1.10.0",
    "multer": "^1.4.5-lts.1"
  }
}
        

3. Arquitectura del Sistema

3.1 Patrón de Arquitectura

El sistema implementa una arquitectura MVC (Model-View-Controller) adaptada para aplicaciones web modernas:

• Model: Consultas SQL y lógica de datos en archivos de rutas
• View: Archivos HTML estáticos servidos desde /frontend
• Controller: Rutas de Express que procesan las solicitudes

3.2 Arquitectura de Capas

┌─────────────────────────────────────────────────────────┐
│                    CLIENTE (Browser)                     │
│         HTML5 + CSS3 + JavaScript (Vanilla)             │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTP/HTTPS + WebSocket
┌─────────────────────────▼───────────────────────────────┐
│                   SERVIDOR (Node.js)                     │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Express.js (Router)                 │    │
│  │   /api/auth  /api/alumnos  /api/cursos  ...    │    │
│  └─────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Middleware (Security Layer)            │    │
│  │    Helmet | CORS | Rate Limit | Morgan          │    │
│  └─────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │             Socket.IO (Real-time Chat)           │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────┬───────────────────────────────┘
                          │ mysql2 (Connection Pool)
┌─────────────────────────▼───────────────────────────────┐
│                  BASE DE DATOS (MySQL)                   │
│      Tablas: usuarios, alumnos, cursos, pagos, etc.     │
└─────────────────────────────────────────────────────────┘
        

4. Estructura del Proyecto

5. Base de Datos

5.1 Sistema de Gestión

Motor: MySQL 8.0

Charset: utf8mb4

Collation: utf8mb4_unicode_ci

5.2 Tablas Principales

5.3 Conexión a la Base de Datos

// backend/utils/db.js
import mysql from 'mysql2/promise';

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  port: process.env.DB_PORT,
  waitForConnections: true,
  connectionLimit: 10,
  queueLimit: 0
});

export default pool;
        

6. API REST - Endpoints

6.1 Autenticación

Body: { "username": "string", "password": "string" }

Response: { "success": true, "user": {...}, "token": "..." }

6.2 Alumnos

Obtiene lista de todos los alumnos.

Obtiene alumno por ID.

Crea nuevo alumno.

Actualiza alumno existente.

Elimina alumno.

6.3 Cursos

6.4 Pagos

6.5 Classroom

7. Seguridad

7.1 Autenticación

• Contraseñas hasheadas con bcrypt (salt rounds: 10)
• Sesiones manejadas del lado del cliente (localStorage)
• Validación de roles en cada endpoint protegido

7.2 Middleware de Seguridad

// Helmet - Cabeceras HTTP seguras
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"]
    }
  }
}));

// Rate Limiting - Prevención de ataques
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutos
  max: 1000 // máximo de requests
});
app.use('/api/', limiter);

// CORS - Orígenes permitidos
const corsOptions = {
  origin: ['https://cemi.up.railway.app'],
  credentials: true
};
        

7.3 Validación de Datos

• Sanitización de inputs para prevenir SQL Injection
• Uso de consultas parametrizadas
• Validación de tipos de datos en el servidor

8. Instalación y Configuración

8.1 Prerrequisitos

• Node.js v18 o superior
• MySQL 8.0
• Git

8.2 Instalación Local

# Clonar repositorio
git clone https://github.com/eduardogabrielmendozaprogram/cemi-sistema-educativo.git

# Ingresar al directorio
cd cemi-sistema-educativo

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con credenciales

# Iniciar servidor de desarrollo
npm run dev
        

8.3 Variables de Entorno (.env)

# Base de Datos
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=cemi_db
DB_PORT=3306

# Servidor
PORT=3000
NODE_ENV=development

# URLs
FRONTEND_URL=http://localhost:3000
        

9. Despliegue en Producción

9.1 Railway

El sistema está desplegado en Railway con las siguientes configuraciones:

# railway.toml
[build]
builder = "nixpacks"

[deploy]
startCommand = "npm start"
healthcheckPath = "/api/health"
healthcheckTimeout = 100
restartPolicyType = "on_failure"
        

9.2 Proceso de Despliegue

1. Push a la rama main de GitHub
2. Railway detecta cambios automáticamente
3. Se ejecuta el build con Nixpacks
4. Se despliega la nueva versión
5. Health check verifica el estado

9.3 URL de Producción

https://cemi.up.railway.app

10. Mantenimiento

10.1 Logs y Monitoreo

• Morgan: Logging de requests HTTP
• Railway Dashboard: Métricas y logs en tiempo real
• Health Check: /api/health

10.2 Backup de Base de Datos

# Exportar base de datos
mysqldump -u root -p cemi_db > backup_cemi.sql

# Importar backup
mysql -u root -p cemi_db < backup_cemi.sql
        

10.3 Actualización del Sistema

1. Realizar backup de la BD
2. Crear rama de desarrollo
3. Implementar cambios
4. Probar en entorno local
5. Merge a main
6. Verificar despliegue automático