backend-mcp
Version:
Generador automático de backends con Node.js, Express, Prisma y módulos configurables. Servidor MCP compatible con npx para agentes IA. Soporta PostgreSQL, MySQL, MongoDB y SQLite.
589 lines (515 loc) • 14 kB
YAML
module:
name: notifications
version: 1.0.0
description: Sistema completo de notificaciones multi-canal con soporte para push, email, SMS, in-app y webhooks
category: communication
author: MCP Backend Modular
license: MIT
# Condiciones de activación
activation:
keywords:
- notification
- notifications
- push
- alert
- alerts
- messaging
- notify
- announcement
- broadcast
- real-time
- firebase
- fcm
- apns
- sms
- twilio
- webhook
- in-app
patterns:
- "send notification"
- "push notification"
- "real-time alerts"
- "notification system"
- "messaging service"
- "broadcast message"
# Puntos de entrada del módulo
entry_points:
service: src/notifications/notifications.service.ts
gateway: src/notifications/notifications.gateway.ts
controller: src/notifications/notifications.controller.ts
module: src/notifications/notifications.module.ts
queue: src/notifications/queue/notification.queue.ts
providers: src/notifications/providers/
templates: src/notifications/templates/
scheduler: src/notifications/scheduler/notification.scheduler.ts
# Dependencias
dependencies:
required:
- database
optional:
- auth
- logging
- cache
- websockets
- email
- queue
# Variables de entorno
environment:
required:
- NOTIFICATIONS_ENABLED
optional:
# Firebase/FCM
- FIREBASE_PROJECT_ID
- FIREBASE_PRIVATE_KEY
- FIREBASE_CLIENT_EMAIL
- FCM_SERVER_KEY
# Apple Push Notifications
- APNS_KEY_ID
- APNS_TEAM_ID
- APNS_BUNDLE_ID
- APNS_PRIVATE_KEY
- APNS_PRODUCTION
# SMS (Twilio)
- TWILIO_ACCOUNT_SID
- TWILIO_AUTH_TOKEN
- TWILIO_PHONE_NUMBER
# Webhooks
- WEBHOOK_SECRET
- WEBHOOK_TIMEOUT
# Configuración general
- NOTIFICATION_QUEUE_ENABLED
- NOTIFICATION_RETRY_ATTEMPTS
- NOTIFICATION_BATCH_SIZE
- NOTIFICATION_RATE_LIMIT
- NOTIFICATION_TEMPLATES_PATH
# Características principales
features:
channels:
- push_notifications
- email_notifications
- sms_notifications
- in_app_notifications
- webhook_notifications
- browser_notifications
providers:
- firebase_fcm
- apple_apns
- twilio_sms
- custom_webhook
- websocket_realtime
functionality:
- template_system
- notification_queue
- batch_processing
- scheduled_notifications
- notification_preferences
- delivery_tracking
- retry_mechanism
- rate_limiting
- notification_history
- analytics_tracking
- user_subscriptions
- device_management
- notification_categories
- priority_levels
- localization_support
# Endpoints de API
api_endpoints:
- method: POST
path: /notifications/send
description: Enviar notificación individual
auth_required: true
- method: POST
path: /notifications/broadcast
description: Enviar notificación masiva
auth_required: true
permissions: ["notifications:broadcast"]
- method: POST
path: /notifications/schedule
description: Programar notificación
auth_required: true
- method: GET
path: /notifications/history
description: Historial de notificaciones
auth_required: true
- method: GET
path: /notifications/preferences
description: Preferencias de usuario
auth_required: true
- method: PUT
path: /notifications/preferences
description: Actualizar preferencias
auth_required: true
- method: POST
path: /notifications/devices
description: Registrar dispositivo
auth_required: true
- method: DELETE
path: /notifications/devices/:deviceId
description: Eliminar dispositivo
auth_required: true
- method: GET
path: /notifications/templates
description: Listar plantillas
auth_required: true
permissions: ["notifications:manage"]
- method: POST
path: /notifications/templates
description: Crear plantilla
auth_required: true
permissions: ["notifications:manage"]
- method: GET
path: /notifications/analytics
description: Analíticas de notificaciones
auth_required: true
permissions: ["notifications:analytics"]
# Archivos generados
generated_files:
- src/notifications/notifications.service.ts
- src/notifications/notifications.gateway.ts
- src/notifications/notifications.controller.ts
- src/notifications/notifications.module.ts
- src/notifications/queue/notification.queue.ts
- src/notifications/scheduler/notification.scheduler.ts
- src/notifications/providers/firebase.provider.ts
- src/notifications/providers/apns.provider.ts
- src/notifications/providers/twilio.provider.ts
- src/notifications/providers/webhook.provider.ts
- src/notifications/providers/websocket.provider.ts
- src/notifications/templates/notification.template.ts
- src/notifications/interfaces/notification.interface.ts
- src/notifications/dto/notification.dto.ts
- src/notifications/entities/notification.entity.ts
- src/notifications/guards/notification.guard.ts
- src/notifications/decorators/notification.decorator.ts
# Integración con base de datos
database_integration:
tables:
- name: notifications
description: Registro de notificaciones enviadas
fields:
- id: String (UUID)
- userId: String
- title: String
- body: String
- channel: String
- status: String
- scheduledAt: DateTime
- sentAt: DateTime
- readAt: DateTime
- metadata: Json
- createdAt: DateTime
- updatedAt: DateTime
- name: notification_templates
description: Plantillas de notificaciones
fields:
- id: String (UUID)
- name: String
- title: String
- body: String
- channel: String
- variables: Json
- isActive: Boolean
- createdAt: DateTime
- updatedAt: DateTime
- name: notification_preferences
description: Preferencias de usuario
fields:
- id: String (UUID)
- userId: String
- channel: String
- enabled: Boolean
- settings: Json
- createdAt: DateTime
- updatedAt: DateTime
- name: user_devices
description: Dispositivos registrados
fields:
- id: String (UUID)
- userId: String
- deviceToken: String
- platform: String
- appVersion: String
- isActive: Boolean
- lastUsed: DateTime
- createdAt: DateTime
- updatedAt: DateTime
- name: notification_analytics
description: Analíticas de notificaciones
fields:
- id: String (UUID)
- notificationId: String
- event: String
- timestamp: DateTime
- metadata: Json
# Integración con autenticación
auth_integration:
permissions:
- notifications:send
- notifications:broadcast
- notifications:manage
- notifications:analytics
- notifications:templates
user_context:
- user_id: Para notificaciones personalizadas
- user_preferences: Para respetar configuraciones
- user_devices: Para envío a dispositivos específicos
# Integración con otros módulos
module_integration:
websockets:
- real_time_notifications
- notification_status_updates
- typing_indicators
email:
- email_notification_fallback
- rich_email_templates
- email_tracking
cache:
- template_caching
- user_preferences_cache
- device_token_cache
logging:
- notification_audit_logs
- delivery_tracking
- error_logging
# Canales de notificación
channels:
push:
platforms:
- ios
- android
- web
providers:
- firebase_fcm
- apple_apns
features:
- rich_notifications
- action_buttons
- custom_sounds
- badges
email:
features:
- html_templates
- attachments
- tracking
- scheduling
sms:
providers:
- twilio
- custom
features:
- international_support
- delivery_reports
- opt_out_handling
in_app:
features:
- real_time_delivery
- read_receipts
- notification_center
- persistence
webhook:
features:
- custom_payloads
- retry_logic
- signature_verification
- timeout_handling
# Tipos de notificación
notification_types:
- system_alerts
- user_messages
- promotional
- transactional
- security_alerts
- reminders
- announcements
- updates
# Niveles de prioridad
priority_levels:
- low
- normal
- high
- urgent
- critical
# Sistema de plantillas
template_system:
engines:
- handlebars
- mustache
- custom
variables:
- user_data
- dynamic_content
- localization
- conditional_blocks
features:
- template_inheritance
- partial_templates
- template_validation
- preview_mode
# Ejemplos de uso
examples:
basic_notification:
description: "Envío básico de notificación"
code: |
await notificationService.send({
userId: 'user123',
title: 'Nueva mensaje',
body: 'Tienes un nuevo mensaje',
channel: 'push'
});
scheduled_notification:
description: "Notificación programada"
code: |
await notificationService.schedule({
userId: 'user123',
title: 'Recordatorio',
body: 'No olvides tu cita',
channel: 'push',
scheduledAt: new Date('2024-01-15T10:00:00Z')
});
broadcast_notification:
description: "Notificación masiva"
code: |
await notificationService.broadcast({
title: 'Mantenimiento programado',
body: 'El sistema estará en mantenimiento',
channels: ['push', 'email'],
audience: { role: 'user' }
});
template_notification:
description: "Notificación con plantilla"
code: |
await notificationService.sendFromTemplate({
templateId: 'welcome-template',
userId: 'user123',
variables: {
userName: 'Juan',
appName: 'Mi App'
}
});
# Instrucciones para agentes de IA
ai_instructions:
setup:
- "Detectar automáticamente proveedores de notificación disponibles"
- "Configurar canales según variables de entorno"
- "Generar plantillas base para cada tipo de notificación"
- "Configurar cola de notificaciones si está habilitada"
usage:
- "Usar el servicio de notificaciones para envíos simples"
- "Implementar gateway para notificaciones en tiempo real"
- "Configurar preferencias de usuario automáticamente"
- "Manejar errores de entrega con reintentos"
best_practices:
- "Respetar preferencias de usuario"
- "Implementar rate limiting"
- "Usar plantillas para consistencia"
- "Trackear métricas de entrega"
- "Manejar tokens de dispositivo expirados"
# Scripts de automatización
automation_scripts:
- name: generate-template
description: Generar nueva plantilla de notificación
command: node scripts/generate-notification-template.js
- name: test-providers
description: Probar conectividad con proveedores
command: node scripts/test-notification-providers.js
- name: cleanup-devices
description: Limpiar dispositivos inactivos
command: node scripts/cleanup-inactive-devices.js
- name: analytics-report
description: Generar reporte de analíticas
command: node scripts/generate-analytics-report.js
# Pruebas
testing:
unit_tests:
- notification.service.spec.ts
- notification.gateway.spec.ts
- firebase.provider.spec.ts
- template.service.spec.ts
integration_tests:
- notification-flow.e2e.spec.ts
- provider-integration.e2e.spec.ts
- queue-processing.e2e.spec.ts
load_tests:
- bulk-notification.load.spec.ts
- concurrent-sending.load.spec.ts
# Métricas de rendimiento
performance_metrics:
throughput:
- notifications_per_second: 1000+
- batch_processing_size: 100-1000
- queue_processing_rate: 500/min
latency:
- push_notification_delivery: <2s
- email_notification_delivery: <30s
- sms_notification_delivery: <10s
- in_app_notification_delivery: <100ms
reliability:
delivery_success_rate: ">99%"
retry_success_rate: ">95%"
uptime: ">99.9%"
# Optimización
optimization:
caching:
- template_cache: 1h
- user_preferences_cache: 30min
- device_tokens_cache: 24h
batching:
- batch_size: 100-1000
- batch_timeout: 5s
- parallel_batches: 10
rate_limiting:
- per_user: 100/hour
- per_app: 10000/hour
- burst_limit: 10/min
# Escalado
scaling:
horizontal:
- queue_workers: auto-scale
- notification_processors: load-balanced
- database_sharding: by_user_id
vertical:
- memory_optimization: template_caching
- cpu_optimization: batch_processing
- io_optimization: connection_pooling
limits:
- max_concurrent_notifications: 10000
- max_queue_size: 1000000
- max_template_size: 10KB
# Seguridad
security:
features:
- webhook_signature_verification
- device_token_encryption
- rate_limiting
- input_validation
- audit_logging
best_practices:
- secure_token_storage
- encrypted_communications
- access_control
- data_privacy
- gdpr_compliance
# Compatibilidad
compatibility:
node_versions:
- ">=16.0.0"
frameworks:
- nestjs: ">=9.0.0"
- express: ">=4.18.0"
databases:
- postgresql: ">=12.0"
- mysql: ">=8.0"
- mongodb: ">=5.0"
providers:
- firebase: ">=9.0.0"
- twilio: ">=3.0.0"
- apns2: ">=11.0.0"
# Documentación
documentation:
- README.md
- API.md
- PROVIDERS.md
- TEMPLATES.md
- DEPLOYMENT.md
- TROUBLESHOOTING.md