# 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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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

```markdown
# 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í ✅ |