SkillStat

Plataforma de inteligencia de mercado laboral tecnológico para México: ingesta de vacantes en tiempo real, extracción automática de habilidades mediante NLP, y un dashboard analítico (Panorama) con tendencias, salarios y demanda regional.

API: https://skillstat.onrender.com
Web: https://skillstat-ss.onrender.com
Status: Producción, hosting gratuito (Render Free Tier)

---

Resumen

El mercado laboral tecnológico en México es opaco, las bolsas de trabajo muestran vacantes individuales, no patrones de mercado, y los reportes especializados son anuales, costosos o dirigidos a empresas. SkillStat convierte el volumen disperso de vacantes en información accionable; qué habilidades suben o bajan en demanda, en qué ciudades, con qué salarios, y cómo evoluciona eso semana a semana, combinando datos en tiempo real, análisis automático de habilidades vía NLP, granularidad geográfica local, y acceso completamente gratuito.

El sistema se construyó bajo arquitectura orientada a servicios (SOA) en cuatro capas: acceso, procesos, servicios, recursos; con separación estricta entre la capa de servicios y el framework web: la lógica de negocio no conoce que Flask existe. El backend expone una API REST consumida por un frontend en JavaScript vanilla sin frameworks, desplegados como servicios independientes.

---

Arquitectura

SkillStat/
├── backend/
│ ├── app/
│ │ ├── controllers/            # Blueprints Flask (capa de acceso HTTP)
│ │ ├── services/               # Lógica de negocio, agnóstica de Flask
│ │ ├── repositories/           # Patrón Repositorio sobre SQLAlchemy
│ │ ├── models/                 # Modelos de datos (SQLAlchemy)
│ │ ├── schemas/                # Validación de entrada (Marshmallow)
│ │ ├── clients/                # Clientes de APIs externas (Adzuna, Nominatim)
│ │ └── utils/                  # Decoradores, manejo de errores, respuestas
│ ├── migrations/               # Alembic
│ └── tests/                    # pytest (unit + integration)
├── frontend/
│ ├── assets/js/api/            # Cliente HTTP compartido, wrappers por dominio
│ ├── assets/js/pages/          # Lógica específica por vista
│ ├── assets/js/components/     # Navbar, drawer, autenticación Google
│ └── views/                    # HTML, multi-página (sin SPA)
└── scripts/                    # Seeds, utilidades de mantenimiento

Decisiones de diseño

• Capa de servicios agnóstica de framework. app/services/ no importa nada de Flask, permite testear lógica de negocio sin levantar una aplicación web completa, y facilita una eventual migración de framework sin reescribir reglas de negocio.
• Patrón Repositorio sobre SQLAlchemy. Cada acceso a datos pasa por un repositorio dedicado, desacoplando la capa de servicios del ORM concreto.
• JWT en cookie httpOnly, no en el cuerpo de la respuesta. El token vive en una cookie httpOnly para que scripts XSS no puedan leerlo directamente vía document.cookie; el token CSRF se solicita bajo demanda vía un endpoint autenticado, en vez de leerse de una cookie legible por JavaScript, porque backend y frontend viven en subdominios distintos de onrender.com (Public Suffix List), que el navegador aísla entre sí para lectura de cookies vía JS.
• Frontend sin framework. Multi-página, JavaScript vanilla, sin build step; decisión deliberada de simplicidad dado el alcance del proyecto.
• Roles con CheckConstraint a nivel de base de datos. Los valores válidos de rol (REGISTERED, ADMIN) están restringidos en el esquema, no solo en la capa de aplicación.

---

Integraciones de APIs

Terceros:

• Adzuna → ingesta de vacantes de empleo en tiempo real.
• Nominatim (OpenStreetMap) → geocodificación de ubicaciones.
• Resend → envío de correos transaccionales (verificación de cuenta, recuperación de contraseña).
• Google Identity Services → autenticación OAuth.

Propias:

• Skills Extraction Service → extracción de habilidades técnicas desde texto de vacantes, vía procesamiento de lenguaje natural (spaCy, modelo es_core_news_sm).
• Market Trends Service → cálculo de tendencias y snapshots agregados de mercado.

---

Calidad y Testing

cd backend

# Ejecutar la suite completa
pytest

# Con reporte de cobertura
pytest --cov=app --cov-report=xml

144 tests (unitarios e integración), corridos en cada Pull Request hacia develop vía GitHub Actions, contra una instancia real de PostgreSQL en el runner de CI. Cobertura reportada a Codecov en cada corrida.

---

Desarrollo Local

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Variables de entorno: copiar backend/.env.example a backend/.env y completar
flask db upgrade
flask run

Frontend

cd frontend
python -m http.server 5500

Nota: accede siempre por http://127.0.0.1:5500 (no localhost:5500). El backend levanta por defecto en 127.0.0.1:5000; si frontend y backend se acceden bajo hosts distintos (localhost vs 127.0.0.1), el navegador trata las peticiones como cross-site y bloquea las cookies de sesión (SameSite=Lax), incluso en desarrollo local. Verifica también que ningún otro proceso (ej. la extensión Five Server de VS Code) siga escuchando en el mismo puerto antes de levantar el servidor, dos procesos compitiendo por el mismo puerto producen comportamiento intermitente y difícil de diagnosticar.

Poblar datos de prueba

# Desde la raíz del proyecto, con el entorno virtual de backend/ activo
python scripts/seed_db.py

---

Despliegue

Desplegado en Render (Free Tier): backend como Web Service, frontend como Static Site, base de datos en Neon (PostgreSQL gestionado), respaldos en Cloudflare R2.

Build command del backend incluye la descarga del modelo de spaCy, requerida para la extracción de habilidades:

pip install -r requirements.txt && python -m spacy download es_core_news_sm

Start command con timeout extendido, dado que la ingesta y extracción NLP son operaciones síncronas y pesadas:

gunicorn -t 300 run:app

El pipeline diario (generación de snapshots de tendencias y evaluación de alertas) se dispara vía GitHub Actions programado, contra un endpoint protegido por clave compartida, ver .github/workflows/daily-pipeline.yml.

---

Gestión de Secretos

• Desarrollo: variables en backend/.env (nunca versionado, ver .env.example para la plantilla).
• Producción: variables de entorno configuradas directamente en el dashboard de Render.
• Ningún secreto real vive en el repositorio ni en el historial de commits.

---

Estado del Proyecto

Desarrollado para la Universidad Tecnológica de Ciudad Juárez, con arquitectura y disciplina de ingeniería pensadas para sostenerse más allá del entregable académico.

Completo y en producción: autenticación (email/contraseña + Google OAuth con vinculación de cuentas), gestión de perfil y habilidades, dashboard de Panorama, comparación de habilidades, alertas de mercado, panel de administración (usuarios, respaldos), sistema de respaldo/restauración vía Cloudflare R2.

Deuda técnica conocida, declarada explícitamente:

• Manejo de excepciones genérico en BaseRepository.save(), captura correctamente errores de integridad, pero enmascara la causa raíz de otros fallos de base de datos bajo el mismo código de error.
• Constante de fallback geográfico duplicada entre ingestion_service.py y trend_snapshot_repository.py, sin fuente única compartida.
• Columna expires_at en tokens de verificación de correo sin timezone explícito, inconsistente con created_at del mismo modelo.
• Bandera de configuración SCHEDULER_ENABLED sin ningún punto de arranque real que la consulte (código muerto).
• Dependencia google-auth sin versión anclada en requirements.txt; resend anclado a versión exacta sin margen de parches automáticos.
• Versión de Python en desarrollo local puede diferir de la versión fijada en CI (3.12), se recomienda usar 3.12 para paridad exacta con el pipeline de pruebas.

Ninguno de estos puntos afecta la funcionalidad observable del sistema en producción; se documentan aquí como parte de la disciplina de gestión de deuda técnica del proyecto, no como fallas ocultas.

---

Licencia

Distribuido bajo la Licencia MIT. Ver LICENSE para más detalles.