template-saas/docs/00-vision-general/VISION-TEMPLATE-SAAS.md

id	title	type	status	priority	version	created_date	updated_date
VIS-002	Vision Template SaaS Multi-Tenant	Vision	Published	P0	1.0.0	2026-01-07	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