Primer commit - Sprint 1

ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# 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 iniciales
+
+- **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.
+
+## 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.