CyberDetective Academy
Plataforma gamificada para entrenar habilidades de investigación digital, ciberseguridad y análisis de datos mediante ejercicios interactivos.
## Descripción
CyberDetective Academy es una aplicación web de aprendizaje basada en retos. Los usuarios resuelven casos prácticos, acumulan puntos, consultan rankings y pueden participar en dinámicas por equipos o modo conferencia.
El proyecto está pensado para capacitaciones, talleres y demostraciones sobre investigación digital, análisis de evidencia, detección de patrones sospechosos y buenas prácticas de ciberseguridad.
## Características
- Ejercicios interactivos con validación automática.
- Sistema de puntos, progreso e intentos por usuario.
- Rankings individuales y por equipos.
- Modo conferencia para eventos en vivo.
- Panel de administración con gestión de usuarios, estado del juego y guía del presentador.
- Backend con autenticación JWT, PostgreSQL y endpoints REST.
- Frontend responsive construido con React, Vite y Framer Motion.
## Stack técnico
| Capa | Tecnologías |
| --- | --- |
| Frontend | React 19, Vite, React Router, Axios, Framer Motion |
| Backend | Node.js, Express, JWT, Helmet, Morgan, Socket.io |
| Base de datos | PostgreSQL |
| Contenedores | Docker, Docker Compose, Nginx |
| Deploy | Railway |
## Estructura del repositorio
.
├── backend/ # API, modelos, rutas, migraciones y seeds
├── frontend/ # Aplicación React + Vite
├── docs/ # Documentación técnica y assets del repo
├── docker-compose.yml # Stack local con PostgreSQL, API y frontend
├── deploy-railway.md # Guía de despliegue
├── INSTALL.md # Instalación rápida
├── LICENSE # Licencia MIT
└── README.md
## Requisitos
- Node.js 18 o superior.
- PostgreSQL 14 o superior.
- npm.
- Docker Desktop o Docker Engine, opcional para levantar el stack completo.
## Configuración local
### 1. Backend
cd backend
npm install
cp .env.example .env
Edita `backend/.env` con tus credenciales de PostgreSQL y un `JWT_SECRET` propio.
npm run setup:db
npm run dev
La API queda disponible en:
http://localhost:3001
### 2. Frontend
En otra terminal:
cd frontend
npm install
cp .env.example .env
npm run dev
La aplicación queda disponible en:
http://localhost:5173
## Docker
También puedes levantar frontend, backend y PostgreSQL con Docker Compose:
docker compose up --build
URLs principales:
Frontend: http://localhost:8080
API: http://localhost:3001
Health: http://localhost:3001/health
El stack local ejecuta el setup inicial de la base de datos al arrancar el backend. Antes de reutilizar `docker-compose.yml` como base para un entorno real, cambia `POSTGRES_PASSWORD`, `JWT_SECRET` y los orígenes CORS.
La guía completa está en [`docs/docker.md`](docs/docker.md).
## Variables de entorno
Usa los archivos de ejemplo como base:
- `backend/.env.example`
- `frontend/.env.example`
Variables principales del backend:
DATABASE_URL=
DB_HOST=localhost
DB_PORT=5432
DB_USER=cyberdetective
DB_PASSWORD=
DB_NAME=cyberdetective_db
JWT_SECRET=change-this-secret
CLIENT_URL=http://localhost:5173
FRONTEND_URL=http://localhost:5173
RUN_DB_SETUP_ON_START=false
REQUEST_BODY_LIMIT=1mb
RATE_LIMIT_MAX=300
Para crear o actualizar un administrador:
ADMIN_USERNAME=
ADMIN_PASSWORD=
ADMIN_NAME=
ADMIN_EMAIL=
Luego ejecuta:
cd backend
npm run create:admin
El repositorio no incluye credenciales reales ni usuarios admin por defecto.
## Scripts útiles
### Backend
npm run dev # Servidor local con nodemon
npm start # Servidor de producción
npm run setup:db # Setup completo de base de datos
npm run create:admin # Crea o actualiza admin desde variables de entorno
npm run migrate:admin # Aplica tablas admin y crea admin si hay variables
### Frontend
npm run dev # Servidor de desarrollo
npm run build # Build de producción
npm run lint # Revisión ESLint
npm run preview # Preview del build
## Verificación
Comandos recomendados antes de publicar cambios:
cd frontend
npm run lint
npm run build
cd backend
npm audit --audit-level=moderate
node --check src/index.js
## Despliegue
La guía de Railway está en [`deploy-railway.md`](deploy-railway.md) y la guía Docker está en [`docs/docker.md`](docs/docker.md).
## Seguridad del repositorio
- No subas archivos `.env` reales.
- No versionar dumps locales, backups SQL, logs, builds ni `node_modules`.
- Si necesitas datos de ejemplo, agrégalos como seeds o migraciones dentro de `backend/src/db`.
## Licencia
Este proyecto está publicado bajo licencia MIT. Ver [`LICENSE`](LICENSE).