template-saas/orchestration/_archivo/planes/PLAN-SPRINT-4-DOCS.md

PLAN SPRINT 4 - Documentation ADRs

Proyecto: template-saas Sprint: 4 Objetivo: Crear Architecture Decision Records y documentación técnica Fecha Inicio: 2026-01-10 SP Total: 5

---

RESUMEN EJECUTIVO

Estado Actual

• Documentación existente: PROJECT-STATUS.md, inventarios YAML
• ADRs: 0 - No existen
• API Docs: Parcial (Swagger básico)

Gap a Cerrar

Crear documentación arquitectónica formal:

1. ADR-001: Multi-tenancy con RLS
2. ADR-002: Autenticación JWT + OAuth
3. ADR-003: Billing con Stripe
4. ADR-004: Notificaciones Real-time
5. ADR-005: Feature Flags System

---

TAREAS DEL SPRINT

DOC-001: ADR Multi-tenancy

Agente: Docs-Agent SP: 1 Dependencia: Ninguna

Entregables

entregables:
  - docs/architecture/adr/ADR-001-multi-tenancy-rls.md

Contenido

• Contexto y problema
• Opciones consideradas (schema per tenant, RLS, app-level)
• Decisión: PostgreSQL RLS
• Consecuencias positivas y negativas
• Implementación actual

---

DOC-002: ADR Autenticación

Agente: Docs-Agent SP: 1 Dependencia: Ninguna Paralelo con: DOC-001

Entregables

entregables:
  - docs/architecture/adr/ADR-002-authentication-jwt-oauth.md

Contenido

• JWT vs Session-based
• Refresh token strategy
• OAuth 2.0 providers
• MFA implementation
• Token storage (httpOnly cookies vs localStorage)

---

DOC-003: ADR Billing

Agente: Docs-Agent SP: 1 Dependencia: Ninguna Paralelo con: DOC-001, DOC-002

Entregables

entregables:
  - docs/architecture/adr/ADR-003-billing-stripe.md

Contenido

• Stripe vs otros providers
• Webhook handling strategy
• Subscription lifecycle
• Plan limits enforcement
• Metered billing approach

---

DOC-004: ADR Notificaciones

Agente: Docs-Agent SP: 1 Dependencia: Ninguna

Entregables

entregables:
  - docs/architecture/adr/ADR-004-notifications-realtime.md

Contenido

• WebSocket vs SSE vs Polling
• Push notifications (VAPID)
• Queue processing (BullMQ)
• Multi-channel strategy
• Delivery guarantees

---

DOC-005: ADR Feature Flags

Agente: Docs-Agent SP: 1 Dependencia: Ninguna

Entregables

entregables:
  - docs/architecture/adr/ADR-005-feature-flags.md

Contenido

• Build vs Runtime flags
• Tenant vs User level
• Gradual rollout strategy
• A/B testing support
• Flag evaluation caching

---

TEMPLATE ADR

# ADR-XXX: [Título]

## Estado
[Propuesto | Aceptado | Deprecado | Reemplazado]

## Contexto
[Descripción del problema o necesidad]

## Decisión
[La decisión tomada]

## Opciones Consideradas
1. [Opción 1] - Pros/Cons
2. [Opción 2] - Pros/Cons
3. [Opción 3] - Pros/Cons

## Consecuencias

### Positivas
- [Beneficio 1]
- [Beneficio 2]

### Negativas
- [Trade-off 1]
- [Trade-off 2]

## Referencias
- [Link 1]
- [Link 2]

---

EJECUCIÓN DEL SPRINT

Orden de Ejecución

Todos en paralelo:
├── DOC-001 (Multi-tenancy)
├── DOC-002 (Auth)
├── DOC-003 (Billing)
├── DOC-004 (Notifications)
└── DOC-005 (Feature Flags)

Métricas de Éxito

Métrica	Objetivo
ADRs creados	5
Decisiones documentadas	5
Referencias cruzadas	Completas

---

ESTRUCTURA DE ARCHIVOS

docs/
├── architecture/
│   ├── adr/
│   │   ├── ADR-001-multi-tenancy-rls.md
│   │   ├── ADR-002-authentication-jwt-oauth.md
│   │   ├── ADR-003-billing-stripe.md
│   │   ├── ADR-004-notifications-realtime.md
│   │   └── ADR-005-feature-flags.md
│   └── README.md (índice)

---

Creado: 2026-01-10 Sprint: 4 de 5 Estado: COMPLETADO

---

REPORTE DE EJECUCIÓN

Fecha Completado: 2026-01-10

Entregables Generados

ADR	Archivo	Estado
ADR-001	docs/architecture/adr/ADR-001-multi-tenancy-rls.md	✅ Creado
ADR-002	docs/architecture/adr/ADR-002-authentication-jwt-oauth.md	✅ Creado
ADR-003	docs/architecture/adr/ADR-003-billing-stripe.md	✅ Creado
ADR-004	docs/architecture/adr/ADR-004-notifications-realtime.md	✅ Creado
ADR-005	docs/architecture/adr/ADR-005-feature-flags.md	✅ Creado

Contenido de ADRs

1. ADR-001 Multi-tenancy RLS

   • Opciones: DB per tenant, Schema per tenant, RLS
   • Decisión: PostgreSQL Row-Level Security
   • Implementación con app.current_tenant_id

2. ADR-002 Autenticación JWT

   • Opciones: Session-based, JWT+Refresh, OAuth-only
   • Decisión: JWT con Refresh Tokens + OAuth opcional
   • Access Token 15min, Refresh Token 7 días
   • MFA con TOTP

3. ADR-003 Billing Stripe

   • Opciones: Custom, Stripe, Paddle/Lemonsqueezy
   • Decisión: Stripe Billing
   • Webhooks críticos documentados
   • Customer Portal integrado

4. ADR-004 Notificaciones Real-time

   • Opciones: Polling, SSE, WebSocket+BullMQ
   • Decisión: Socket.io + BullMQ
   • Canales: Email, Push, In-app, SMS (futuro), WhatsApp
   • VAPID para push notifications

5. ADR-005 Feature Flags

   • Opciones: Hardcoded, LaunchDarkly, Sistema propio
   • Decisión: Sistema propio con PostgreSQL
   • Override por tenant/usuario
   • Rollout gradual soportado

Métricas Finales

Métrica	Objetivo	Resultado
ADRs creados	5	5 ✅
SP completados	5	5 ✅
Formato consistente	Sí	Sí ✅