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)

[![CI/CD](https://github.com/math2/platform/actions/workflows/test.yml/badge.svg)](https://github.com/math2/platform/actions)
[![Coverage](https://codecov.io/gh/math2/platform/branch/main/graph/badge.svg)](https://codecov.io/gh/math2/platform)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-20%2B-brightgreen.svg)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](docker/README.md)
[![TypeScript](https://img.shields.io/badge/typescript-5.4-blue.svg)](https://www.typescriptlang.org/)

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

```bash
# 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](docs/API.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Security](docs/SECURITY.md)
- [Deployment](docs/DEPLOYMENT.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## Testing

```bash
# 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

```bash
# 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](LICENSE)

## Equipo

- **Maintainers**: Ver [CONTRIBUTORS.md](CONTRIBUTORS.md)
- **Changelog**: Ver [CHANGELOG.md](CHANGELOG.md)

## Soporte

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

---

<p align="center">
  Built with ❤️ by the Math2 Platform Team
</p>