6.1 KiB
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_idy 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.