# 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 Core

### 1. Auth (Autenticacion)
- JWT con refresh tokens
- OAuth 2.0 (Google, Microsoft, GitHub)
- MFA opcional
- Session management
- Password policies

### 2. Tenants (Multi-tenancy)
- Creacion y gestion de tenants
- Configuracion por tenant
- Aislamiento de datos via RLS
- Limites y cuotas

### 3. Users (Usuarios)
- CRUD de usuarios por tenant
- Roles y permisos
- Invitaciones
- Perfiles

### 4. Billing (Facturacion)
- Integracion Stripe
- Suscripciones y pagos recurrentes
- Facturas y recibos
- Metricas de uso
- Webhooks de Stripe

### 5. Plans (Planes)
- Definicion de planes (Free, Starter, Pro, Enterprise)
- Features por plan
- Limites configurables
- Upgrades/downgrades

### 6. AI Integration
- Agnostico de proveedor (Claude, OpenAI, Gemini)
- Configuracion de prompts por tenant
- Rate limiting
- Tracking de uso

### 7. Notifications
- Email (templates)
- Push notifications
- In-app notifications
- WhatsApp Business (opcional)

### 8. Audit Logs
- Registro de acciones
- Retencion configurable
- Busqueda y filtrado
- Exportacion

### 9. Feature Flags
- Flags por tenant
- Rollout gradual
- A/B testing
- Configuracion dinamica

### 10. Webhooks
- Outgoing webhooks
- Retry logic
- Firma de payloads
- Logs de entregas

### 11. Storage
- Abstraccion de almacenamiento
- S3/MinIO compatible
- CDN integration
- Limites por tenant

### 12. CRUD Base
- Generadores de CRUD
- Validacion automatica
- Paginacion estandar
- Filtros y busqueda

---

## 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-07