Onboarding Unificado — PrivaSteward

0. Lectura obligatoria antes de tocar código

Lee en este orden antes de escribir una sola línea:

1. Qué es PrivaSteward

Plataforma web de Transafety Ltda. para gestionar el cumplimiento de la Ley 21.719 de Protección de Datos de Chile (vigente 1-dic-2026). Permite a organizaciones documentar, controlar y demostrar su cumplimiento normativo.

Stack

1.1 Flask — el backend

Flask es un micro-framework web para Python. "Micro" no significa limitado, sino que no impone estructura: no trae ORM, ni autenticación, ni plantillas prefijadas. Tú decides qué agregas. Esto lo hace ideal para proyectos que crecen con disciplina propia.

En PrivaSteward, Flask es el núcleo que:

• Recibe cada petición HTTP y la dirige al blueprint correspondiente (una forma de agrupar rutas por módulo).
• Ejecuta los decoradores de seguridad (@permission_required, @login_required) antes de llegar a la lógica.
• Retorna HTML renderizado (vía Jinja2) o JSON (vía jsonify) según la ruta.
• Se inicializa a través del patrón Application Factory (create_app() en src/app/__init__.py), que permite crear instancias distintas para desarrollo, testing y producción sin cambiar código.

1.2 Bootstrap 5 — el frontend visual

Bootstrap es una biblioteca CSS (y JavaScript) de código abierto creada por Twitter. Provee un sistema de grids responsivos, componentes visuales predefinidos (botones, tablas, modales, alertas, formularios) y utilidades de espaciado, color y tipografía. Su objetivo es que no tengas que escribir CSS desde cero para hacer una interfaz usable y consistente.

En PrivaSteward se usa Bootstrap 5 en todos los templates. Cuando ves clases como class="btn btn-primary" o class="table table-striped" en los archivos .html, esas son clases de Bootstrap que ya traen estilo incorporado. Modificar la apariencia de un componente generalmente significa cambiar o agregar clases de Bootstrap, no escribir CSS custom.

1.3 Jinja2 — el motor de plantillas

Jinja2 es el motor de plantillas de Python que usa Flask. Permite escribir archivos HTML con "agujeros" que se rellenan con datos dinámicos cuando el servidor construye la respuesta.

Las tres construcciones que más verás en src/app/templates/:

El template base (templates/base.html) contiene el layout común (sidebar, navbar, scripts de Bootstrap). Cada módulo extiende ese base con {% extends "base.html" %} y solo define su contenido propio dentro de {% block content %}...{% endblock %}.

1.4 SQLAlchemy — ORM

SQLAlchemy es el ORM (Object-Relational Mapper) de Python. Traduce clases Python a tablas de base de datos y viceversa. En vez de escribir SQL crudo, defines modelos como class User(BaseModel) y SQLAlchemy genera las queries. En desarrollo se usa SQLite (un archivo local, sin servidor); en QA y producción, PostgreSQL.

1.5 Docker y la infraestructura AWS

¿Qué es Docker?

Docker es una herramienta que empaqueta una aplicación junto con todo lo que necesita para funcionar — Python, las dependencias de requirements.txt, las variables de entorno base, el comando de arranque — dentro de una unidad llamada contenedor. El contenedor es idéntico sin importar dónde se ejecute: en tu laptop, en el servidor de QA o en producción en AWS.

La analogía más útil: imagina que en vez de entregar una receta (el código fuente) que cada cocinero tiene que interpretar con sus propios ingredientes y utensilios, entregas una comida ya preparada en un tupper sellado. El resultado es siempre el mismo.

Los dos conceptos que debes distinguir:

El archivo Dockerfile en la raíz del proyecto describe cómo construir la imagen de PrivaSteward: parte de una imagen base de Python, copia el código, instala las dependencias y define el comando de arranque (gunicorn apuntando a create_app()).

PrivaSteward corre íntegramente en Amazon Web Services. Los cuatro servicios que debes conocer:

15 módulos y su estado

2. Arquitectura real (datos del grafo — 7.887 nodos, 10.757 aristas)

2.1 God Nodes — las abstracciones más acopladas

Estos son los nodos con más conexiones. Tocarlos tiene el mayor radio de impacto. Úsalos con cuidado y siempre corre graphify affected "<nodo>" --depth 2 antes de modificarlos.

2.2 Flujo de una request típica

2.3 Patrón Service — cómo está organizada la lógica

2.4 Multitenancy — lo más importante para no romper datos

2.5 Ciclos de import detectados (advertencia)

3. Setup del entorno (una vez)

# 1. Clonar
git clone https://github.com/gveraTrnsfty/LeydeProtecciondeDatos.git
cd LeydeProtecciondeDatos

# 2. Entorno virtual
python -m venv venv
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Linux/Mac:
source venv/bin/activate

# 3. Dependencias
pip install -r src/requirements.txt

# 4. Variables de entorno (SQLite funciona sin config adicional)
cp .env.example .env   # Linux/Mac
copy .env.example .env # Windows

# 5. Hooks de calidad
pip install pre-commit && pre-commit install

# 6. Levantar
python src/run.py   # → http://localhost:5000

Tests antes de cualquier commit

pytest tests/unit/ -v --tb=short          # obligatorio
pytest tests/integration/ -v              # para cambios en servicios
pytest --cov=src/app --cov-report=html    # cobertura

Accesos que necesitas

• GitHub: colaborador en gveraTrnsfty/LeydeProtecciondeDatos
• .env configurado con tus valores locales
• AWS CLI (solo si haces deploys): aws configure
• QA URL: https://qa.leydeprotecciondatos.cl/

4. Flujo Git (no negociable)

git checkout develop && git pull origin develop
git checkout -b feature/mi-tarea
# ...trabajar...
git commit -m "feat(arcop): agregar endpoint GET /api/arcop/requests"
git push origin feature/mi-tarea
# → abrir PR a develop en GitHub

Conventional Commits obligatorio

Alcances válidos: auth rat arcop consent policy incident dashboard dpia dp_roles api db deploy

Reglas duras

5. Trabajar con el agente IA (Claude Code)

5.0 Política de uso de IA — obligatorio leer

5.1 Regla base: micro-sesiones y carga bajo demanda

• Un chat nuevo por cada tarea no relacionada (evita context rot).
• No pegues archivos enteros. Deja que el agente use Read, Grep, Glob.
• Al cambiar de sesión: el agente genera resumen_traspaso.md con lo logrado y lo pendiente.

5.2 Graphify — navega el código sin quemar tokens

El grafo está construido en graphify-out/ (7.887 nodos, commit c799a5b9). Invócalo con /graphify en Claude Code.

# Actualizar el grafo (sin costo LLM)
graphify update .

5.3 Skills disponibles

5.4 Thinking levels — razonamiento extendido del modelo

¿Qué significa que un LLM "piense"?

Los modelos de lenguaje como Claude generan respuestas token a token. Normalmente el modelo produce la respuesta directamente. Con extended thinking (razonamiento extendido), el modelo primero genera un bloque de razonamiento interno — una especie de borrador mental donde puede explorar alternativas, detectar contradicciones y corregir su propio razonamiento — antes de producir la respuesta final que el usuario ve.

Este proceso es análogo a pedirle a un experto que "piense en voz alta antes de responder" en lugar de dar la primera respuesta que se le ocurra. Para tareas simples no cambia nada. Para tareas complejas — un bug sutil de concurrencia, diseñar la arquitectura de un módulo nuevo, interpretar un artículo legal — puede ser la diferencia entre una respuesta superficial y una correcta.

Los tres niveles de thinking

En Claude Code se controlan con --thinking low|medium|high (o en la UI con el selector de razonamiento). Cada nivel determina cuántos tokens internos de "pensamiento" puede usar el modelo antes de responder:

Ejemplos concretos en PrivaSteward

5.5 Worktrees — humano y agente trabajando en paralelo

¿Qué es un worktree?

Normalmente cuando usas Git, tienes una sola carpeta de trabajo asociada a tu repositorio. Si quieres cambiar de rama, haces git checkout otra-rama y los archivos de tu carpeta cambian. No puedes estar en dos ramas a la vez en la misma carpeta.

Un git worktree te permite tener múltiples carpetas de trabajo distintas del mismo repositorio, cada una en una rama diferente, al mismo tiempo. Comparten la misma historia de Git (el mismo .git/ interno) pero tienen sistemas de archivos separados. Es como abrir el mismo proyecto en dos ventanas del explorador, cada una mostrando una rama distinta, sin interferir entre sí.

¿Por qué es útil con agentes IA?

Cuando le das una tarea larga a Claude Code, el agente puede tardar varios minutos modificando archivos. Sin worktrees, mientras el agente trabaja en tu carpeta principal, tú no puedes tocar esos archivos sin crear conflictos. Con un worktree:

• El agente trabaja en ../privasteward-agente/ en su propia rama feature/tarea-del-agente.
• Tú sigues trabajando en LeydeProtecciondeDatos/ en tu propia rama sin ninguna interferencia.
• Cuando el agente termina, revisas el diff, haces merge o cherry-pick, y borras el worktree.

Comandos

# 1. Crear el worktree para el agente (crea carpeta hermana + nueva rama)
git worktree add ../privasteward-agente feature/tarea-del-agente

# 2. El agente trabaja en ../privasteward-agente
#    Tú sigues trabajando en LeydeProtecciondeDatos/ normalmente

# 3. Ver todos los worktrees activos
git worktree list

# 4. Cuando terminas: eliminar el worktree y la rama (si ya hiciste merge)
git worktree remove ../privasteward-agente
git branch -d feature/tarea-del-agente

5.6 Definition of Done para una tarea con agente

6. Contexto legal — artículos clave de la Ley 21.719

7. Tu primera tarea — checklist

• Leí CLAUDE.md, ARQUITECTURA_TECNICA.md, PENDIENTES.md
• Entorno levantado: python src/run.py responde en :5000
• pytest tests/unit/ pasa en mi máquina
• Corrí: graphify explain "<el servicio que voy a tocar>"
• Corrí: graphify affected "<el servicio o model>" --depth 2
• Creé rama feature/ desde develop actualizado
• Definí ALCANCE explícito (archivos a crear / modificar / NO tocar)
• Implementé SOLO lo aprobado, con test por cada función nueva
• flake8 + pytest verdes + grep de credenciales limpio
• Commit Conventional + PR a develop + decision log si hay decisión de diseño

8. Estructura del proyecto

LeydeProtecciondeDatos/
├── CLAUDE.md                   # Documento maestro
├── Dockerfile / docker-compose.yml
├── .env.example
├── pyproject.toml / .pre-commit-config.yaml
│
├── src/app/
│   ├── __init__.py             # create_app() — 64 importadores
│   ├── extensions.py           # db, login_manager, limiter, mail, csrf
│   ├── decorators.py           # @permission_required — 15 blueprints lo importan
│   ├── middleware/tenant.py    # get_tenant_scoped_or_404() — 129 conexiones ⚠️
│   ├── models/                 # 25+ modelos SQLAlchemy (BaseModel como base)
│   ├── routes/                 # 15+ blueprints Flask
│   ├── services/               # Lógica de negocio (EmailService es transversal)
│   ├── forms/                  # Formularios WTForms
│   ├── templates/              # 150+ templates Jinja2
│   ├── static/                 # CSS, JS, imágenes
│   └── api/                    # Endpoints REST
│
├── tests/
│   ├── unit/                   # 30+ archivos
│   ├── integration/
│   ├── e2e/                    # Playwright
│   └── security/
│
├── config/                     # development / qa / production / testing
├── docs/                       # 70+ archivos de documentación
├── scripts/                    # Seeds, utilidades, datasets de demo
├── migrations/                 # Migraciones Alembic
└── graphify-out/               # Grafo de conocimiento (no commitear cambios aquí)

9. Contacto