--- id: "VIS-002" title: "Vision Template SaaS Multi-Tenant" type: "Vision" status: "Published" priority: "P0" version: "1.0.0" created_date: "2026-01-07" updated_date: "2026-01-24" --- # VISION - Template SaaS Multi-Tenant **Proyecto:** template-saas **Version:** 1.0.0 **Estado:** Referencia **Tipo:** Template --- ## Proposito Template de referencia para construir aplicaciones SaaS multi-tenant con arquitectura moderna, escalable y segura. Diseñado para servir como base para cualquier proyecto SaaS dentro del workspace. --- ## Objetivos del Template ### Objetivo Principal Proporcionar una base solida y probada para el desarrollo de aplicaciones SaaS que incluya: 1. **Multi-tenancy completo** - Aislamiento de datos por tenant con RLS 2. **Sistema de billing integrado** - Stripe como proveedor principal 3. **Multiples portales** - Landing, App, Admin, Super-Admin 4. **Integracion IA** - Soporte para LLMs (Claude, OpenAI, Gemini) 5. **Comunicacion multi-canal** - WhatsApp Business, Email, Push ### Objetivos Secundarios - Reducir tiempo de desarrollo de nuevos proyectos SaaS en 60%+ - Establecer patrones consistentes en todo el workspace - Facilitar la propagacion de mejoras entre proyectos - Documentar mejores practicas de manera ejecutable --- ## Arquitectura General ``` ┌─────────────────────────────────────────────────────────────────┐ │ PORTALES │ ├─────────────────┬─────────────────┬─────────────────┬──────────┤ │ Landing │ App │ Admin │ Super │ │ (publico) │ (tenants) │ (tenants) │ Admin │ └────────┬────────┴────────┬────────┴────────┬────────┴────┬─────┘ │ │ │ │ └─────────────────┴─────────────────┴──────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ BACKEND API │ │ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │ │ │ Auth │ Tenants │ Users │ Billing │ Plans │ AI │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ │ │ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │ │ │ Notif. │ Audit │ Feature │ Webhooks│ Storage │ CRUD │ │ │ │ │ Logs │ Flags │ │ │ Base │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ DATABASE │ │ PostgreSQL 16+ con Row-Level Security │ │ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │ │ │ auth │ tenants │ users │ billing │ plans │ audit │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Modulos del Template (22 Total) ### Categoria 1: Core (12 modulos) #### 1. Auth (SAAS-001) - JWT con refresh tokens - OAuth 2.0 ready (ver SAAS-015) - MFA opcional - Session management - Password policies #### 2. Tenants (SAAS-002) - Creacion y gestion de tenants - Configuracion por tenant - Aislamiento de datos via RLS - Limites y cuotas #### 3. Users (SAAS-003) - CRUD de usuarios por tenant - Roles y permisos (RBAC) - Invitaciones - Perfiles #### 4. Billing (SAAS-004) - Integracion Stripe - Suscripciones y pagos recurrentes - Facturas y recibos - Metricas de uso - Webhooks de Stripe #### 5. Plans (SAAS-005) - Definicion de planes (Free, Starter, Pro, Enterprise) - Features por plan - Limites configurables - Upgrades/downgrades #### 6. AI Integration (SAAS-006) - Agnostico de proveedor (Claude, OpenAI, Gemini) - Configuracion de prompts por tenant - Rate limiting - Tracking de uso #### 7. Notifications (SAAS-007) - Email (templates) - Push notifications - In-app notifications - WebSocket real-time (v2.0) #### 8. Audit Logs (SAAS-008) - Registro de acciones - Retencion configurable - Busqueda y filtrado - Exportacion #### 9. Feature Flags (SAAS-009) - Flags por tenant - Rollout gradual - A/B testing - Configuracion dinamica #### 10. Webhooks (SAAS-010) - Outgoing webhooks con BullMQ - Retry logic exponencial - Firma de payloads - Logs de entregas #### 11. Storage (SAAS-011) - Abstraccion de almacenamiento - S3/R2/MinIO compatible - CDN integration - Limites por tenant #### 12. CRUD Base (SAAS-012) - Generadores de CRUD - Validacion automatica - Paginacion estandar - Filtros y busqueda --- ### Categoria 2: Comunicacion (2 modulos) #### 13. Email (SAAS-013) - Multiples proveedores (SendGrid, SES, SMTP) - Templates con variables - Tracking de envios - Configuracion por tenant #### 14. WhatsApp (SAAS-014) - WhatsApp Business API - Templates aprobados - Mensajes interactivos - Webhook de respuestas --- ### Categoria 3: Integraciones (1 modulo) #### 15. OAuth 2.0 (SAAS-015) - Google, Microsoft, GitHub, Apple - Vincular/desvincular cuentas - SSO corporativo ready - Gestion de conexiones --- ### Categoria 4: Extended Features (7 modulos) #### 16. Analytics (SAAS-016) - Dashboard de metricas - KPIs de usuarios, billing, uso - Graficos temporales - Exportacion de datos #### 17. Reports (SAAS-017) - Exportacion PDF/Excel/CSV - Templates predefinidos - Filtros por fecha/criterios - Envio por email #### 18. Sales Foundation (SAAS-018) - Gestion de leads - Pipeline de oportunidades - Seguimiento de actividades - Dashboard de ventas #### 19. Portfolio (SAAS-019) - Catalogo de productos/servicios - Categorias jerarquicas - Precios multi-moneda - Variantes de productos #### 20. Commissions (SAAS-020) - Esquemas configurables - Calculo automatico - Periodos de pago - Reportes de earnings #### 21. MLM (SAAS-021) - Estructuras: Unilevel, Binario, Matriz - Comisiones multinivel - Sistema de rangos - Visualizacion de red #### 22. Goals (SAAS-022) - Metas numericas/porcentuales - Asignacion individual/equipo - Tracking automatico - Notificaciones de hitos --- ## Portales ### Landing Portal (Publico) - Home page - Pricing - Features - Registro - Login - Documentacion ### App Portal (Usuarios Tenant) - Dashboard - Funcionalidades de negocio - Configuracion de cuenta - Soporte ### Admin Portal (Administradores Tenant) - Gestion de usuarios - Configuracion del tenant - Reportes - Billing ### Super Admin Portal (Plataforma) - Gestion de tenants - Metricas globales - Configuracion del sistema - Logs de auditoria --- ## Integraciones ### Obligatorias - **Stripe** - Pagos y suscripciones - **PostgreSQL 16+** - Base de datos con RLS - **Redis** - Cache y sesiones ### Opcionales - **OpenRouter/LLM** - Integracion IA - **WhatsApp Business** - Comunicacion - **SendGrid/SES** - Email - **S3/MinIO** - Storage - **Sentry** - Error tracking --- ## Principios de Diseno 1. **Tenant-First** - Todo diseno considera multi-tenancy desde el inicio 2. **Security by Default** - RLS, validaciones, sanitizacion 3. **Provider Agnostic** - Abstracciones para cambiar proveedores 4. **Feature Flagged** - Nuevas features detras de flags 5. **Audit Everything** - Registro de acciones criticas 6. **API First** - Backend como API, frontends como consumidores --- ## Metricas de Exito | Metrica | Objetivo | |---------|----------| | Tiempo de setup nuevo proyecto | < 4 horas | | Cobertura de tests | > 80% | | Documentacion | 100% modulos documentados | | Seguridad | 0 vulnerabilidades criticas | | Performance | < 200ms respuesta API | --- ## Roadmap del Template ### Fase 1 - Foundation (Base) - Database schema con RLS - Auth module - Tenants module - Users module ### Fase 2 - Billing - Stripe integration - Plans y suscripciones - Webhooks de pago ### Fase 3 - Features - Feature flags - Notifications - Audit logs ### Fase 4 - Portales - Landing portal - App portal - Admin portal - Super admin portal ### Fase 5 - Integraciones - AI/LLM integration - WhatsApp Business - Storage --- ## Referencias - Arquitectura: `ARQUITECTURA-MULTI-TENANT.md` - Inventario: `orchestration/inventarios/MASTER_INVENTORY.yml` - Contexto: `orchestration/00-guidelines/CONTEXTO-PROYECTO.md` --- **Creado:** 2026-01-07 **Actualizado:** 2026-01-24