math2-platform/docs/history/README_2024-03-30.md

⚠️ DISCLAIMER: DOCUMENTO OBSOLETO

Estado: Este README ha sido archivado por contener información inflada.
Fecha: 2026-03-30
Problemas conocidos:

• Promete ">80% cobertura" → Realidad: ~11%
• Menciona "CSRF tokens" → Realidad: No implementado
• Menciona "DOMPurify" → Realidad: No usamos DOMPurify

README actual: Ver README.md en raíz (actualizado)
Documentación honesta: docs/current/README.md

---

Math2 Platform - Enterprise Edition (OBSOLETO)

Sistema profesional de aprendizaje de matemáticas con álgebra lineal.

Características

• Plataforma Completa: Frontend Next.js 14, Backend Node.js/Express, PostgreSQL, Redis
• Seguridad Enterprise: JWT con blacklist, rate limiting, XSS protection, CSRF tokens
• AI Integration: Generación de ejercicios con modelos LLM (MiniMax-M2.5)
• Gamificación: Sistema de rankings, badges, streaks con timezone support
• Dockerizado: Multi-stage builds, SSL/TLS, health checks
• Testing: >80% cobertura backend, E2E con Playwright

Requisitos

• Node.js 20+
• Docker & Docker Compose
• PostgreSQL 15+
• Redis 7+

Instalación Rápida

# 1. Clonar repositorio
git clone https://github.com/math2/platform.git
cd platform

# 2. Configurar variables de entorno
./scripts/setup-secrets.sh

# 3. Iniciar con Docker
docker-compose up -d

# 4. Ejecutar migraciones
cd backend && npx prisma migrate deploy

# 5. Seed de datos
npm run db:seed

Acceso

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• API Documentation: http://localhost:3001/api-docs

Documentación

• API Documentation
• Architecture
• Security
• Deployment
• Contributing
• Changelog

Testing

# Unit tests
npm run test

# E2E tests
npx playwright test

# Coverage
npm run test:coverage

# Backend specific
cd backend && npm test

# Frontend specific
cd frontend && npm test

Arquitectura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Next.js 14    │────▶│  Node.js API    │────▶│   PostgreSQL    │
│   (Frontend)    │     │   (Backend)     │     │   (Primary DB)  │
│   Port: 3000    │     │   Port: 3001    │     │   Port: 5432    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
│   Redis         │
│  (Cache/Queue)  │
│   Port: 6379    │
└─────────────────┘

Workers:
┌─────────────────┐  ┌──────────────────┐  ┌─────────────────────┐
│   PDF Worker    │  │ Exercise Worker  │  │ Notification Worker│
│  (Process PDFs) │  │  (AI Generate)   │  │  (Telegram Bot)     │
└─────────────────┘  └──────────────────┘  └─────────────────────┘

Stack Tecnológico

Frontend

• Framework: Next.js 14 (App Router)
• Lenguaje: TypeScript 5.4 (strict mode)
• Estilos: Tailwind CSS + shadcn/ui
• State: Zustand
• Math: KaTeX
• Testing: Vitest + React Testing Library

Backend

• Runtime: Node.js 20 LTS
• Framework: Express 4.x
• Lenguaje: TypeScript 5.4
• ORM: Prisma 5.x
• Auth: JWT + bcrypt (cost 12)
• Validation: Zod
• Logging: Winston (JSON structured)
• Testing: Vitest + Supertest
• Queue: Bull + Redis

Infrastructure

• Primary DB: PostgreSQL 15
• Cache/Queue: Redis 7
• Migrations: Prisma Migrate
• Proxy: Nginx (rate limiting, SSL)
• AI: MiniMax-M2.5 (Aliyun DashScope)
• Notifications: Telegram Bot API

Seguridad

• OWASP Top 10 compliance
• JWT con refresh tokens y blacklist (Redis)
• Rate limiting por IP y usuario (Express + Redis)
• XSS protection en fórmulas matemáticas (DOMPurify)
• CSRF tokens en forms y validación de Origin
• SQL injection prevention con Prisma ORM
• Input validation con Zod en todos los endpoints
• Password hashing con bcrypt (cost 12)
• Helmet.js security headers
• CORS configurado

Estructura del Proyecto

math2/
├── backend/              # Node.js API
│   ├── src/
│   │   ├── modules/      # Domain modules
│   │   ├── shared/       # Utils, middleware, types
│   │   └── workers/      # Background workers
│   ├── prisma/           # Schema & migrations
│   └── tests/            # Unit & integration tests
├── frontend/             # Next.js 14 App
│   ├── src/
│   │   ├── app/          # Next.js App Router
│   │   ├── components/   # React components
│   │   ├── lib/          # Utils & API client
│   │   ├── store/        # Zustand stores
│   │   └── hooks/        # Custom hooks
│   └── public/           # Static assets
├── docker/               # Docker configuration
│   ├── docker-compose.yml
│   ├── Dockerfile.backend
│   ├── Dockerfile.frontend
│   ├── Dockerfile.worker
│   └── nginx.conf
├── docs/                 # Documentation
├── scripts/              # Automation scripts
├── pdfs/                 # Source PDF files
└── .github/              # GitHub templates & workflows

Comandos Útiles

# Desarrollo
npm run dev              # Start all services
docker-compose up -d     # Start with Docker

# Database
cd backend && npx prisma migrate deploy
npm run db:seed

# Testing
npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

# Linting & Formatting
npm run lint
npm run type-check
npm run format

# Docker
docker-compose logs -f   # View logs
docker-compose ps        # Service status
docker-compose down -v   # Stop & remove volumes

# Escalar workers
docker-compose up -d --scale exercise-worker=3

Licencia

MIT License - Ver LICENSE

Equipo

• Maintainers: Ver CONTRIBUTORS.md
• Changelog: Ver CHANGELOG.md

Soporte

• Issues: https://github.com/math2/platform/issues
• Security: security@mathplatform.com
• Documentation: https://docs.mathplatform.com

---

Built with ❤️ by the Math2 Platform Team