motor-de-encuestas/ARCHITECTURE.md

# ARCHITECTURE.md — Plataforma de Encuestas Soberanas

> Nombre/marca: **decisión Nivel 3 pendiente** (ver `CLAUDE.md` → Decisiones abiertas).
> Codename provisional del repo: `encuestas-soberanas`.
> Última edición: ver historial de git. Este documento es el ancla; los detalles vivos van en los ADR.

---

## 1. Contexto

La organización corre **encuestas de descubrimiento** (clientes, asistentes a talleres, ciudadanos)
y hoy las herramientas disponibles (Google Forms, ClickUp Forms) son insuficientes en cuatro ejes:
flexibilidad de tipos de pregunta, lógica condicional, autenticación/anonimato, y tabulación
posterior. El volumen no justifica una suite profesional, y se requiere **soberanía total sobre los
datos** porque se tratan datos sensibles (salud/discapacidad).

El caso fundacional es el **mapeo de cuidadores** en organizaciones: colaboradores que cuidan a
personas con discapacidad o adultos mayores. Hay 4 empresas concretas listas para correr la encuesta
en esta primera etapa.

Sobre ese caso se monta un objetivo de mayor alcance: desarrollar en Paraguay el concepto de
**"economía de la discapacidad"** mediante un mapeo de la vinculación, agregando datos de múltiples
empresas para identificar patrones y tendencias a nivel país.

## 2. Propuesta de valor

Una plataforma propia de encuestas con dos niveles de lectura que conviven:

- **Nivel empresa (operativo, confidencial):** cada empresa recibe SU dashboard para diagnosticar y
  decidir acciones sobre su gente — siempre sobre agregados, nunca sobre individuos.
- **Nivel macro (estudio país):** patrones y tendencias cruzando todas las empresas, base de la
  "economía de la discapacidad".

El diferencial real no es "otro Google Forms propio", sino: **(a)** motor de lógica condicional sin
límites, **(b)** reportes cruzados (filtrar respuesta A por respuesta B), **(c)** experiencia móvil
fluida, y **(d)** soberanía + cumplimiento de la Ley 7593/2025 desde el diseño (privacy by design).

## 3. Lo que NO es (esta etapa)

- **NO** es el builder visual de encuestas todavía. Esta etapa corre **una encuesta fija** (mapeo de
  cuidadores) desplegada multi-empresa. El builder es el núcleo a futuro, no lo que se necesita HOY.
- **NO** implementa el modelo de lectura macro **atribuible** (Nivel 3). Las 4 encuestas de esta
  etapa son anónimas; el dato queda permanentemente en Nivel 1/2.
- **NO** implementa re-identificación ni re-contacto de respondentes (incompatible con anónimo).
- **NO** implementa corresponsabilidad de tratamiento (solo Modo A en v1; ver ADR-001).
- **NO** integra el LLM (generación de encuestas / análisis de texto / resumen PDF) en v1 — está en
  `BACKLOG.md`, es diferencial pero no fundacional.

## 4. Stack

Decidido en **ADR-002**. Resumen:

| Capa | Tecnología | Razón |
|---|---|---|
| Frontend | Next.js (App Router) | SSR/SSG, ecosistema maduro, buena DX |
| Form engine | React + react-hook-form + zod | Flexible, validación tipada, sin lock-in |
| Backend / datos | Supabase (Postgres + Auth + RLS + Realtime) | Soberanía, self-host posible, RLS nativo |
| Reportes/gráficos | ECharts (o Recharts) | Gratis, potente, no-SaaS |
| Deploy | Vercel + Supabase — **residencia de datos a confirmar** | Ver ADR-002, decisión abierta |

> ⚠️ La **residencia de los datos** (Supabase Cloud US/EU vs self-host) NO está cerrada y es
> relevante para "soberanía" + transferencia internacional bajo Ley 7593. Ver ADR-002.

## 5. Modelo de datos

Especificado en **`DATA_MODEL.md`** (contrato de esquema). Claude Code implementa las migraciones y
las policies de RLS en la Etapa 1 a partir de ese contrato; no inventa tablas.

Principios estructurales (de ADR-001):
- Anonimato **por-encuesta** (propiedad de configuración, no global de plataforma).
- Las 4 encuestas de v1: **anónimas a nivel respondente**, conservando `company_id` y
  cuasi-identificadores (edad, sector, zona) → mantiene vivo el Nivel 2 y la comparación por segmento.
- `respondent_id` (clave pseudónima) **reservado en el esquema pero NO usado** en estas encuestas.
- Consentimiento granular **versionado e inmutable** por respuesta (ADR-003).
- Dos ejes ortogonales de clasificación: **sensibilidad legal** (alimenta consentimiento) y
  **seguridad** (alimenta RLS/cifrado).
- **Umbral de k-anonimato** obligatorio en toda visualización compartida (nunca mostrar celda con
  n < umbral).

## 6. ADRs

Ver `docs/adr/` para los archivos completos.

- **ADR-001** — Modelo de privacidad y gobierno de datos *(el corazón del producto)*.
- **ADR-002** — Stack tecnológico y residencia de datos.
- **ADR-003** — Consentimiento granular versionado e inmutable.
- **ADR-004** — Capa de identidad y autenticación (SSO Keycloak para staff; sin login para respondentes).
- **ADR-005** — Esquema declarativo de formularios y estrategia de dos fases (Sprint 4). La lógica del flujo vive en datos (JSONB), interpretada por un motor backend; el frontend wizard es un renderer sin reglas de negocio. Motor genérico diferido a Fase 2.

## 7. Riesgos

| # | Riesgo | Mitigación |
|---|---|---|
| R1 | Re-identificación por cruce de cuasi-identificadores (empresas chicas, n=1) | Umbral de k-anonimato mandatorio en visualización; texto libre fuera del store analítico |
| R2 | Incumplimiento Ley 7593/2025 con datos sensibles | Privacy by design; validación con asesor legal paraguayo **antes** de producción con datos reales |
| R3 | Residencia de datos contradice "soberanía" | Decidir self-host vs cloud en ADR-002 antes de cargar datos reales |
| R4 | Construir "otro Google Forms" (mediocridad) | Invertir en lógica condicional, reportes cruzados y UX móvil — no en cantidad de features |
| R5 | Confusión anónimo vs pseudónimo en el equipo/agente | Distinción documentada textual en ADR-001 + regla en CLAUDE.md |
| R6 | Scope creep al builder visual antes de validar el caso fijo | "Lo que NO es" explícito; builder en BACKLOG, no en sprint 1 |

> **Disclaimer legal:** este proyecto trata datos sensibles. Ninguno de estos documentos es asesoría
> legal. La Ley 7593/2025 aún no tiene reglamentación publicada. Validar el flujo de consentimiento y
> tratamiento con un especialista paraguayo antes de recolectar datos reales.