Nocron Backend

NestJStypescriptRESTfulAPINocron


🔗 Ver en GitHub

Resumen del Proyecto Nocron Backend - API de Automatización

🎯 Producto

Nocron Backend es una API RESTful robusta y escalable para automatización de tareas y programación de flujos de trabajo. Es el motor central de la plataforma Nocron, diseñado para eliminar la complejidad de los cron jobs tradicionales mientras proporciona características de nivel empresarial.

Características principales:

  • Programación de tareas basada en cron y eventos
  • Múltiples tipos de triggers (Schedule, Webhook, Email, API)
  • Ejecución en tiempo real con monitoreo en vivo vía WebSockets
  • Sistema de plantillas para casos de uso comunes
  • Autenticación JWT con refresh tokens y rotación automática
  • Control de acceso basado en roles (User, Admin, SuperAdmin)
  • Gestión de API Keys con permisos granulares
  • Analytics avanzado con métricas de engagement y rendimiento
  • Sistema de notificaciones multi-canal (Email, Push, In-App, SMS, Webhook)
  • Integración con Stripe para suscripciones y pagos
  • Integración con Notion API para sincronización de workspaces
  • Auditoría completa con tracking de todas las acciones
  • Alertas de seguridad automáticas con detección de patrones

🛠️ Stack Tecnológico

Backend Framework

  • NestJS 11.0.1 - Framework progresivo de Node.js
  • Node.js 18.17.0+ - Runtime de JavaScript
  • TypeScript 5.7.3 - Superset tipado de JavaScript

Base de Datos

  • PostgreSQL 15+ - Base de datos relacional (Neon Cloud)
  • Prisma ORM 6.15.0 - ORM moderno con type-safety

Autenticación y Seguridad

  • Passport.js - Middleware de autenticación
  • JWT (jsonwebtoken v9.0.2) - Tokens de acceso y refresh
  • Argon2 (v0.44.0) - Hashing de passwords (recomendado)
  • Bcrypt (v6.0.0) - Hashing alternativo de passwords

Validación y Transformación

  • class-validator (v0.14.2) - Validación de DTOs
  • class-transformer (v0.5.1) - Transformación de objetos

Integraciones Externas

  • @notionhq/client v5.1.0 - Integración con Notion API
  • Stripe v18.5.0 - Procesamiento de pagos
  • Nodemailer v7.0.6 - Envío de emails
  • Socket.io v4.8.1 - WebSockets para tiempo real

Programación y Tareas

  • node-cron v3.0.3 - Programador de tareas estilo cron
  • @nestjs/schedule v4.1.2 - Módulo de scheduling de NestJS

Documentación

  • @nestjs/swagger v7.4.2 - Documentación OpenAPI/Swagger
  • swagger-ui-express v5.0.1 - UI interactiva de Swagger

Testing

  • Jest v30.0.0 - Framework de testing
  • ts-jest v29.2.5 - Preset de Jest para TypeScript
  • Supertest v7.0.0 - Testing de APIs HTTP

Herramientas de Desarrollo

  • ESLint v9.18.0 - Linter de código
  • Prettier v3.4.2 - Formateador de código
  • Husky v9.1.7 - Git hooks
  • ts-node v10.9.2 - Ejecución de TypeScript en Node.js
  • tsx v4.19.2 - TypeScript ejecutor rápido

🏗️ Arquitectura

Estructura de Carpetas

nocron/backend/
├── src/                          # Código fuente
│   ├── auth/                     # Autenticación y autorización
│   ├── users/                    # Gestión de usuarios
│   ├── tasks/                    # Sistema central de tareas
│   ├── api/v1/                   # API REST versión 1
│   ├── admin/                    # Panel administrativo
│   ├── analytics/                # Motor de analytics
│   ├── billing/                  # Stripe y suscripciones
│   ├── dashboard/                # Métricas en tiempo real
│   ├── email/                    # Servicio de emails
│   ├── notifications/            # Sistema de notificaciones
│   ├── reports/                  # Reportes y analytics
│   ├── notion/                   # Integración Notion
│   ├── health/                   # Health checks
│   ├── monitoring/               # Monitoreo del sistema
│   ├── auditLog/                 # Logs de auditoría
│   ├── sessions/                 # Gestión de sesiones
│   ├── webhooks/                 # Manejo de webhooks
│   ├── queue/                    # Cola de tareas
│   ├── retry/                    # Sistema de reintentos
│   ├── scheduler/                # Programador de tareas
│   ├── alerts/                   # Alertas de seguridad
│   ├── realtime/                 # WebSockets
│   ├── common/                   # Guards, interceptors, pipes
│   ├── config/                   # Configuración
│   ├── prisma/                   # Prisma service
│   ├── utils/                    # Utilidades
│   ├── app.module.ts             # Módulo raíz
│   ├── app-minimal.module.ts     # Módulo mínimo
│   ├── main.ts                   # Bootstrap principal
│   └── main-minimal.ts           # Bootstrap mínimo
│
├── prisma/                       # Prisma ORM
│   ├── schema.prisma             # Schema de base de datos
│   └── seed.ts                   # Datos iniciales
│
├── test/                         # Tests E2E
│   ├── jest-e2e.json             # Configuración Jest E2E
│   └── jest-smoke.json           # Configuración smoke tests
│
├── docs/                         # Documentación
│   ├── README.md
│   ├── ARCHITECTURE.md
│   ├── DECISIONS.md
│   ├── ROADMAP.md
│   └── nocron_backend_roadmap.md
│
├── .github/                      # GitHub configuration
│   ├── workflows/                # CI/CD workflows
│   └── ISSUE_TEMPLATE/           # Templates de issues
│
├── sdk/                          # SDKs cliente
│   └── javascript/               # SDK JavaScript/TypeScript
│
├── issues/                       # Tracking de auditorías
│   ├── GITHUB-ISSUES-CREATED-SUMMARY.md
│   ├── GITHUB-PROJECT-MANAGEMENT.md
│   ├── SPRINT-PLANNING.md
│   └── PROJECT-WORKFLOW-GUIDE.md
│
├── package.json                  # Dependencias y scripts
├── tsconfig.json                 # Configuración TypeScript
├── nest-cli.json                 # Configuración Nest CLI
├── .env                          # Variables de entorno
├── .env.test                     # Variables para testing
├── .gitignore                    # Git ignore
├── .prettierrc                   # Configuración Prettier
├── eslint.config.mjs             # Configuración ESLint
├── README.md                     # Documentación principal
├── CLAUDE-BACKEND-STATE.md       # Estado del proyecto
└── CONTRIBUTING.md               # Guía de contribución

🔧 Módulos y Servicios

Módulo Auth (src/auth/)

Archivos clave:

  • auth.service.ts - Lógica de autenticación (registro, login, refresh, logout)
  • auth.controller.ts - Endpoints de autenticación
  • roles.service.ts - Gestión de roles y permisos
  • admin-roles.controller.ts - Endpoints administrativos de roles
  • strategies/jwt.strategy.ts - Estrategia JWT de Passport
  • dto/register.dto.ts, login.dto.ts, change-password.dto.ts - DTOs de validación

Funcionalidades:

  • Registro de usuarios con hashing Argon2/Bcrypt
  • Login con JWT access + refresh tokens
  • Refresh token con rotación automática
  • Sistema de roles (User, Admin, SuperAdmin)
  • Guards de autenticación y autorización
  • Token version para invalidación global de tokens

Módulo Users (src/users/)

Funcionalidades:

  • CRUD completo de usuarios
  • Gestión de perfiles
  • Cambio de contraseña
  • Gestión de tokens de Notion
  • Relaciones con tareas y suscripciones

Módulo Tasks (src/tasks/)

Funcionalidades:

  • Creación y gestión de tareas
  • Soporte para múltiples tipos de acciones:
    • HTTP_REQUEST
    • EMAIL_SEND
    • DATABASE_QUERY
    • API_CALL
    • CUSTOM_SCRIPT
    • NOTION_SYNC
  • Scheduling con cron expressions
  • Ejecución inmediata de tareas
  • Logs de ejecución
  • Estados: ACTIVE, PAUSED, STOPPED, FAILED

Módulo API v1 (src/api/v1/)

Endpoints públicos:

  • /api/v1/tasks - CRUD de tareas con autenticación API Key
  • /api/v1/analytics - Métricas y analytics
  • Documentación Swagger en /api/docs

Módulo Billing (src/billing/)

Funcionalidades:

  • Integración completa con Stripe
  • Gestión de suscripciones (BASIC, PRO, ENTERPRISE)
  • Webhook handling para eventos de Stripe
  • Tracking de pagos y facturas
  • Límites de uso por plan
  • Cancelación y renovación de suscripciones

Módulo Notifications (src/notifications/)

Funcionalidades:

  • Sistema multi-canal (Email, Push, In-App, SMS, Webhook)
  • Templates de notificaciones con variables
  • Preferencias de usuario por tipo y canal
  • Tracking de envío, entrega, lectura y clicks
  • Cola de notificaciones
  • Retry logic para fallos

Módulo Email (src/email/)

Funcionalidades:

  • Integración con Nodemailer (SMTP Gmail configurado)
  • Templates con Handlebars
  • Variables dinámicas
  • Tracking de opens y clicks
  • Rate limiting
  • Logs de envío

Módulo Analytics (src/analytics/)

Funcionalidades:

  • Tracking de eventos de usuario
  • Métricas de engagement
  • Análisis de cohortes
  • Funnel analytics
  • Retention metrics
  • Custom events

Módulo Dashboard (src/dashboard/)

Funcionalidades:

  • Métricas en tiempo real
  • Overview de tareas activas
  • Estadísticas de ejecución
  • Gráficos de rendimiento
  • Alertas y notificaciones recientes

Módulo Reports (src/reports/)

Funcionalidades:

  • Reportes ejecutivos
  • Reportes personalizables
  • Exportación en múltiples formatos
  • Scheduling de reportes
  • Histórico de ejecuciones
  • Analytics avanzado

Módulo Admin (src/admin/)

Funcionalidades:

  • Gestión de usuarios
  • Analytics administrativos
  • Control de suscripciones
  • Revisión de audit logs
  • Gestión de alertas de seguridad
  • Configuración del sistema

Módulo Notion (src/notion/)

Funcionalidades:

  • Integración con Notion API (@notionhq/client)
  • Sincronización de workspaces
  • OAuth flow
  • Acceso a bases de datos y páginas
  • Webhooks de Notion

Módulo Health (src/health/)

Endpoints:

  • /health - Health check básico
  • Database connectivity check
  • External services status

Módulo Monitoring (src/monitoring/)

Funcionalidades:

  • System metrics
  • Performance monitoring
  • Error tracking
  • Uptime monitoring

Módulo AuditLog (src/auditLog/)

Funcionalidades:

  • Logging automático de todas las requests
  • Interceptor global
  • TransactionId único por request
  • Captura de request/response completo
  • Metadata de seguridad (IP, User-Agent)
  • Clasificación por tipo de acción
  • Flags de acciones críticas

Módulo Sessions (src/sessions/)

Funcionalidades:

  • Gestión de refresh tokens
  • Tracking de sesiones activas
  • Revocación de sesiones
  • Limpieza de sesiones expiradas
  • Información de dispositivos

Módulo Webhooks (src/webhooks/)

Funcionalidades:

  • Manejo de webhooks de Stripe
  • Retry logic con backoff exponencial
  • Verificación de firmas
  • Idempotencia
  • Logging de eventos

Módulo Queue (src/queue/)

Funcionalidades:

  • Cola de tareas asíncronas
  • Procesamiento en background
  • Priority queues
  • Retry logic
  • Dead letter queue

Módulo Retry (src/retry/)

Funcionalidades:

  • Sistema de reintentos configurable
  • Backoff exponencial
  • Max attempts
  • Error handling

Módulo Scheduler (src/scheduler/)

Funcionalidades:

  • Programación de tareas con node-cron
  • Evaluación de cron expressions
  • Timezone support
  • Next execution calculation

Módulo Alerts (src/alerts/)

Archivos:

  • security-alerts.service.ts - Detección de patrones sospechosos
  • alert-email.service.ts - Envío de alertas por email
  • alert-webhook.service.ts - Envío de alertas por webhook
  • alert-coordinator.service.ts - Coordinación de alertas
  • alerts.controller.ts - Endpoints de gestión de alertas

Funcionalidades:

  • Detección automática de:
    • Múltiples intentos de login fallidos
    • Acceso desde IPs inusuales
    • Burst de accesos admin
    • User agents sospechosos
  • Niveles de severidad (LOW, MEDIUM, HIGH, CRITICAL)
  • Notificaciones multi-canal
  • Acknowledgement y resolución de alertas
  • False positive marking

Módulo Realtime (src/realtime/)

Funcionalidades:

  • WebSockets con Socket.io
  • Notificaciones en tiempo real
  • Updates de tareas en ejecución
  • Dashboard live updates

Módulo Common (src/common/)

Componentes:

  • Guards: JwtAuthGuard, RolesGuard, ApiKeyGuard
  • Interceptors: AuditLogInterceptor, TransformInterceptor
  • Pipes: ValidationPipe customizado
  • Decorators: @Roles(), @Public(), @ApiKey()
  • Filters: HttpExceptionFilter

Módulo Config (src/config/)

Configuración:

  • Database configuration
  • JWT configuration
  • Email configuration
  • Stripe configuration
  • Environment validation

🔐 Seguridad

Protecciones Implementadas

  • Password Hashing - Argon2 (recomendado) + Bcrypt
  • Input Validation - class-validator en todos los DTOs
  • SQL Injection Protection - Prisma ORM con queries parametrizadas
  • XSS Protection - Sanitización de inputs
  • CORS - Configurado para dominios permitidos
  • Rate Limiting - Por endpoint y por API Key
  • Audit Logging - Todas las acciones registradas
  • Security Alerts - Detección automática de patrones sospechosos

📡 API Endpoints

Autenticación

POST   /auth/register          - Registro de usuario
POST   /auth/login             - Login con JWT
POST   /auth/refresh           - Refresh token
POST   /auth/logout            - Logout y revocación de sesión
POST   /auth/change-password   - Cambio de contraseña

Usuarios

GET    /users                  - Listar usuarios (Admin)
GET    /users/:id              - Obtener usuario
PATCH  /users/:id              - Actualizar usuario
DELETE /users/:id              - Eliminar usuario

Tareas (API v1)

GET    /api/v1/tasks              - Listar tareas del usuario
POST   /api/v1/tasks              - Crear nueva tarea
GET    /api/v1/tasks/:id          - Obtener detalle de tarea
PUT    /api/v1/tasks/:id          - Actualizar tarea
DELETE /api/v1/tasks/:id          - Eliminar tarea
POST   /api/v1/tasks/:id/execute  - Ejecutar tarea inmediatamente
GET    /api/v1/tasks/:id/logs     - Obtener logs de ejecución

Dashboard

GET    /dashboard/overview        - Overview general
GET    /dashboard/metrics         - Métricas en tiempo real
GET    /dashboard/recent-tasks    - Tareas recientes

Analytics

GET    /analytics/dashboard       - Dashboard de analytics
GET    /analytics/summary         - Resumen de métricas
GET    /analytics/cohorts         - Análisis de cohortes
GET    /analytics/engagement      - Métricas de engagement

Reports

GET    /reports/executive-summary - Reporte ejecutivo
GET    /reports/custom            - Reportes personalizados
POST   /reports/custom            - Crear reporte personalizado
GET    /reports/:id/execute       - Ejecutar reporte

Admin

GET    /admin/users               - Gestión de usuarios
GET    /admin/analytics           - Analytics administrativos
GET    /admin/audit-logs          - Logs de auditoría
GET    /admin/security-alerts     - Alertas de seguridad
POST   /admin/roles/:userId       - Asignar rol a usuario
DELETE /admin/roles/:userId/:role - Remover rol de usuario

Billing

GET    /billing/subscription      - Obtener suscripción actual
POST   /billing/subscription      - Crear suscripción
PUT    /billing/subscription      - Actualizar suscripción
DELETE /billing/subscription      - Cancelar suscripción
POST   /webhooks/stripe           - Webhook de Stripe

Notifications

GET    /notifications             - Listar notificaciones
GET    /notifications/:id         - Obtener notificación
PATCH  /notifications/:id/read    - Marcar como leída
GET    /notifications/preferences - Obtener preferencias
PUT    /notifications/preferences - Actualizar preferencias

Health & Status

GET    /health                    - Health check
GET    /api/status                - API status

Documentación

GET    /api/docs                  - Swagger UI
GET    /api-json                  - OpenAPI spec JSON

Tipos de Tests

  1. Unit Tests - *.spec.ts en cada módulo
  2. E2E Tests - test/*.e2e-spec.ts contra DB real
  3. Smoke Tests - test/jest-smoke.json para validación rápida

Testing contra DB Real

El proyecto utiliza una base de datos PostgreSQL en Neon para tests E2E, no mocks. Esto asegura que los tests reflejen el comportamiento real.

📊 Auditoría y Quality Assurance

Sistema de Tracking

Issues Críticos Identificados

  1. #1 - Password hashing inconsistency (auth vs users)
  2. #2 - Circular dependencies entre users y auth
  3. #3 - Type safety issues con ‘as any’ casts
  4. #4 - Missing queue management para notificaciones
  5. #5 - Command injection vulnerability en PDF generation

Issues Mayores

  1. #6 - Implementar duplicateTask endpoint
  2. #7 - Reemplazar mock implementations en reports
  3. #8 - Tracking real de duración de tareas
  4. #9 - Campos de DB faltantes (tags, status)
  5. #10 - Rate limiting para email service

Auditoría Completa (2025-09-27)

  • Módulos auditados: 12
  • Issues identificados: 35 (8 critical, 7 major, 20 minor)
  • Production readiness: 75%
  • Score general: ✅ Arquitectura excelente, issues manejables

🔗 Enlaces y Recursos

Desarrollo

GitHub

Base de Datos

  • Provider: Neon PostgreSQL (cloud)

Documentación Externa

📄 Licencia

MIT License - Ver archivo LICENSE para detalles

📞 Soporte

Estado actual: ✅ Backend completo y funcional con 15 issues identificados pendientes para producción

Última actualización: 2025-10-17 Versión del documento: 1.0

Built with ❤️ by the NoCron Team