# Regla: Arquitectura

Las decisiones de arquitectura tienen un costo de cambio muy alto. Esta regla
establece cómo tomar, documentar y mantener las decisiones estructurales del
sistema para que sean reversibles o al menos comprensibles en el futuro.

---

## ADRs — Architecture Decision Records

Toda decisión de arquitectura significativa debe documentarse como un ADR.

¿Qué es significativa? Una decisión que:
- Afecta más de un módulo o equipo
- Es difícil o costosa de revertir
- Tiene alternativas viables que fueron consideradas
- El equipo debatió más de 15 minutos

Formato mínimo de un ADR (`docs/adr/NNN-titulo-corto.md`):
```markdown
# ADR NNN: Título de la decisión

**Fecha**: YYYY-MM-DD
**Estado**: Propuesto | Aceptado | Deprecado | Reemplazado por ADR-NNN

## Contexto
Qué situación o problema motivó esta decisión.

## Decisión
Qué se decidió hacer.

## Consecuencias
Qué implica esta decisión — positivo, negativo, neutral.

## Alternativas consideradas
Qué más se evaluó y por qué se descartó.
```

Reglas de ADRs:
- Numerados secuencialmente, nunca reutilizar un número.
- Inmutables: si una decisión cambia, crear un nuevo ADR que referencia al anterior.
- Versionar con el código — viven en el repositorio.
- Revisar ADRs existentes antes de proponer arquitectura nueva.

### ADRs en estado Propuesto

Un ADR en estado `Propuesto` documenta una decisión evaluada pero **no implementada
todavía** — por ejemplo porque depende de factores externos (roadmap de un tercero,
evidencia futura que hoy no existe, señal de demanda que aún no aparece). Mantener
ADRs en Propuesto indefinidamente sin plan de cierre genera deuda silenciosa —
propuestas que "quedan ahí" y nadie revisa.

**Todo ADR en estado Propuesto DEBE incluir:**

1. **Criterios de disparo** — lista concreta de condiciones que reabren la decisión
   (al menos una por entrada). Ejemplos: "El usuario pide X", "Anthropic publica Y",
   "Contador supera umbral Z".
2. **Fecha límite de reevaluación automática** — entre 6 y 12 meses desde la fecha
   de creación del ADR. Si ninguno de los criterios se cumple antes de la fecha,
   el ADR se mueve a `Descartado` documentando la decisión final.

Un ADR Propuesto sin ambos elementos NO es aceptable — se rechaza en revisión.

**Índice obligatorio**: el archivo `docs/adr/README.md` (o `.planning/adrs/README.md`
en SWL) lista todos los ADRs con estado y fecha de reevaluación visible. Cualquier
persona debe poder ver en una lectura si hay ADRs vencidos sin abrir cada archivo.

---

## Análisis de repositorios externos — filtro de dominio obligatorio

Cuando se analiza un repositorio ajeno para enriquecer el sistema SWL (código en
`temp/`, dependencias, proyectos de referencia), **el primer paso antes de cualquier
análisis profundo** es aplicar el filtro de dominio:

> *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*

Si la respuesta es **NO** porque el repositorio vive en un dominio vertical externo
(fintech/billing, ML Ops, data science, bio-informática, dominios regulados
específicos, etc.), descartar el 80-95% del contenido sin análisis profundo.

**Lo que siempre vale la pena extraer aunque el dominio sea externo:**

- Patrones de configuración de Claude Code: `.claude/settings.json`, hooks, comandos
- Patrones de arquitectura transversales: repository pattern, service layer, etc.
- Configuraciones de CI/CD, Docker, pre-commit
- Patrones de testing, observabilidad, auth

**Lo que se descarta sin análisis aunque esté bien escrito:**

- Lógica de negocio específica del dominio externo
- Integraciones con servicios verticales (Stripe fintech, servicios de ML Ops,
  procesadores de señales médicas)
- Documentación de producto/handbook organizacional

**Patrón validado**: análisis de `temp/polar-main` (fintech, 86 módulos) en
sesión 2026-04-23 → 3% integrado (3 patrones transversales), 97% descartado sin
análisis profundo. Análisis de `temp/estilo-sin-ai-isms` (ecosistema auditor
OIC-INE) → 10% integrado. Aplicar el filtro primero ahorra horas de análisis
de código irrelevante.

---

## Módulos profundos — interfaz pequeña, implementación rica

El principio de módulos profundos (John Ousterhout — A Philosophy of Software Design):

- La interfaz pública de un módulo debe ser MÍNIMA en comparación con la
  complejidad que encapsula.
- Un módulo profundo oculta decisiones de implementación detrás de una abstracción
  simple. Quien lo usa no necesita conocer los detalles.
- Un módulo shallow tiene una interfaz casi tan compleja como su implementación
  — ofrece poco valor de abstracción.

Señales de módulo shallow a corregir:
- Una clase con 15 métodos públicos donde 12 son getters/setters triviales.
- Un service que solo pasa llamadas a otro service sin agregar lógica.
- Una función que solo llama a otra función con los mismos parámetros.

Cómo diseñar módulos profundos:
- Definir la interfaz pública primero, antes de implementar.
- La interfaz solo expone lo que el llamador NECESITA, no lo que es conveniente.
- La implementación puede ser compleja — eso es el punto.
- Documentar la interfaz, no la implementación (la implementación se explica sola
  con código limpio).

---

## Dependency Injection (DI)

- Nunca instanciar dependencias dentro de una clase o función.
  Las dependencias se RECIBEN, no se crean.

  Mal:
  ```python
  class FacturaService:
      def __init__(self):
          self.db = DatabaseConnection()  # dependencia hardcodeada
          self.mailer = SmtpMailer()      # imposible de mockear en tests
  ```

  Bien:
  ```python
  class FacturaService:
      def __init__(self, db: AsyncSession, mailer: MailerProtocol):
          self.db = db
          self.mailer = mailer
  ```

- Usar el contenedor de DI del framework (FastAPI Depends, Angular DI).
- Inyectar interfaces/protocolos, no implementaciones concretas.
- El grafo de dependencias fluye en una dirección: alto nivel → bajo nivel.
  Nunca al revés.

---

## Separación de concerns

Cada módulo tiene UNA responsabilidad principal. Las capas del sistema:

| Capa | Responsabilidad | Lo que NO hace |
|------|----------------|----------------|
| Endpoints / Controllers | Recibir HTTP, delegar al service, devolver respuesta | Lógica de negocio |
| Services | Lógica de negocio, orquestación | Queries SQL directas, formateo HTTP |
| Repositories / DAL | Acceso a datos, queries | Lógica de negocio |
| Schemas / DTOs | Validación y serialización | Lógica de negocio |
| Models / ORM | Estructura de datos en BD | Lógica de negocio |

Reglas estrictas:
- Los endpoints no contienen lógica de negocio — llaman al service.
- Los services no hacen `db.commit()` — el endpoint hace el commit.
- Los models ORM no contienen lógica de negocio compleja — solo helpers
  de presentación simples.
- Los schemas Pydantic no acceden a la BD directamente.

---

## Sin dependencias circulares

- El grafo de dependencias entre módulos debe ser un DAG (grafo dirigido acíclico).
- Módulo A importa a Módulo B → Módulo B NO puede importar a Módulo A.
- Detectar con `import-linter` (Python) o `eslint-plugin-import` (TypeScript).
- Si se detecta una dependencia circular: extraer el tipo o la función compartida
  a un módulo de bajo nivel del que ambos dependan.
- La solución NUNCA es `importlib.import_module()` para romper el ciclo en runtime.

Señales de dependencias circulares inminentes:
- Dos módulos que se referencian mutuamente "solo para un tipo".
- Un módulo `utils` o `helpers` que importa módulos de negocio.
- Un modelo ORM que importa un service.

---

## SOLID

**S — Single Responsibility**: Una clase/módulo, un eje de cambio.
Si una clase cambia por dos razones distintas, tiene dos responsabilidades.

**O — Open/Closed**: Abierto para extensión, cerrado para modificación.
Agregar funcionalidad nueva sin modificar código existente (usando herencia,
composición o strategy pattern, no if/else interminables).

**L — Liskov Substitution**: Un subtipo puede reemplazar a su supertipo.
Si se hereda de una clase, la subclase debe honrar el contrato de la base.
No lanzar excepciones que la base no lanza, no ignorar parámetros.

**I — Interface Segregation**: Interfaces pequeñas y específicas.
No forzar a una clase a implementar métodos que no usa. Preferir varias
interfaces pequeñas sobre una grande.

**D — Dependency Inversion**: Depender de abstracciones, no de implementaciones.
Los módulos de alto nivel no dependen de los de bajo nivel — ambos dependen
de abstracciones (protocolos, interfaces, clases abstractas).

---

## Tres capas de reutilización: regla, skill, fragmento

El sistema SWL distingue tres capas para evitar duplicación. La elección de la
capa correcta depende de cuándo y cómo se carga el contenido:

- **Regla** (`reglas/X.md`): política global cargada por matcher de archivos.
  Aplicable a múltiples agentes y skills. Ejemplo: `reglas/seguridad.md`.
- **Skill** (`habilidades/X/SKILL.md`): conocimiento operacional invocado
  dinámicamente con `Skill("X")`. Tiene frontmatter, descripción y carga
  bajo demanda. Ejemplo: `habilidades/tdd-workflow/SKILL.md`.
- **Fragmento** (`agentes/_X.md`): bloque de prompt compartido por varios
  agentes que se incrusta literalmente en su system prompt. Sin overhead
  runtime, sin frontmatter operacional, no routable por el orquestador.
  Ejemplo: `agentes/_hitl-alto-riesgo.md`.

Antes de crear texto compartido entre agentes, decidir cuál capa aplica. Ver
`reglas/fragmentos-compartidos.md` para la convención completa.

---

## DRY — Don't Repeat Yourself

Si una regla de negocio, una validación, un cálculo o una transformación cambia,
debe cambiar en un solo lugar. Si requiere cambiar en dos o más, hay duplicación
de conocimiento.

Estrategias para eliminar duplicación según el tipo:

- **Lógica de negocio duplicada entre services** → extraer a un service compartido
  o un domain method.
- **Queries duplicadas** → extraer a un método del repositorio.
- **Validaciones repetidas** → centralizar en schemas (Pydantic, Zod, Bean Validation).
- **Configuración repetida** → extraer a variables de entorno o módulo de configuración.
- **Transformaciones de datos repetidas** → extraer a un mapper o utility function.

DRY aplica entre capas: si el frontend valida lo mismo que el backend, el backend
es la fuente de verdad. La validación del frontend es UX, no lógica de negocio.

DRY NO justifica abstracciones prematuras. Si la duplicación es casual (dos cosas
iguales hoy que cambiarán independientemente mañana), dejar duplicado es correcto.
DRY aplica cuando el conocimiento subyacente es el mismo.

---

## Patrones de arquitectura reconocidos

Antes de inventar una solución arquitectural nueva, verificar si alguno de
estos patrones resuelve el problema:

- **Repository Pattern**: Para abstraer el acceso a datos.
- **Command/Query Separation (CQS)**: Operaciones que cambian estado vs. las que leen.
- **Event-driven**: Para desacoplar productores de consumidores.
- **Strangler Fig**: Para migración incremental de sistemas legados.
- **Adapter**: Para integrar sistemas externos con interfaces incompatibles.
- **Saga**: Para transacciones distribuidas entre microservicios.

Documentar en un ADR qué patrón se usa y por qué.

---

## Tablas append-only — excepción documentada a "audit columns nullable=False"

Algunas tablas son **append-only por diseño**: solo se crean filas (INSERT) y
eventualmente se eliminan por purga (DELETE). Nunca se actualizan. Ejemplos
típicos: logs de errores (`bitacora_error`, `error_log`), audit trails inmutables,
telemetría, métricas históricas, event sourcing event store, outbox pattern.

Para estas tablas la regla general del proyecto "`created_by`/`updated_by`
`nullable=False` en tablas transaccionales" **NO aplica**. Documentar la
excepción explícitamente:

1. En el **docstring de la clase modelo** (Python/Java/C#):

```python
class BitacoraError(Base):
    """
    Registro inmutable de un error backend o frontend.

    Tabla append-only: solo se crean filas (INSERT) y se purgan por antigüedad
    (DELETE). Nunca se actualizan. Esta invariante es fundamental para que el
    log de errores sea un audit trail confiable.

    Excepción a regla "audit columns nullable=False":
        La convención del proyecto exige `created_by` y `updated_by` NOT NULL
        en tablas transaccionales. BitacoraError queda exenta porque:
        (a) Es un log del sistema, no una entidad de negocio modificable.
        (b) No tiene `updated_at` ni `updated_by` — no hay concepto de
            "última modificación" en una tabla append-only.
        (c) `usuario_id` es nullable de forma intencional: los errores de
            sesiones no autenticadas (401 antes del login) no tienen usuario.
    """
```

2. En el **comentario del DDL SQL**:

```sql
COMMENT ON TABLE bitacora_error IS
    'Errores backend y frontend persistidos para diagnóstico. '
    'Append-only: solo INSERT y DELETE (purga). '
    'Sin updated_at/updated_by por diseño (excepción documentada en CONTEXTO).';
```

3. En el **GRANT** del rol de aplicación, omitir explícitamente `UPDATE`:

```sql
-- INSERT: para que el sistema cree entradas.
-- SELECT: para que el admin las consulte.
-- DELETE: para que el job de purga elimine antiguas.
-- NO UPDATE: la tabla es append-only por diseño.
GRANT SELECT, INSERT, DELETE ON bitacora_error TO ine_user;
```

**Criterios para considerar una tabla append-only legítima**:

- Toda fila representa un evento ocurrido en un momento específico (immutable in time).
- No hay caso de negocio que requiera modificar la fila después de creada.
- La única forma de "corregir" un dato erróneo es insertar una fila correctora
  posterior (event sourcing) o purgar y re-insertar (telemetría).
- El borrado se hace por política de retención (antigüedad), no por revocación.

**Origen del patrón**: OIC v1.5 Slice 1 (2026-06-04). Patrón portable a cualquier
proyecto con logs estructurados, audit trails o event sourcing.

---

## Split modular con compositor por herencia múltiple

Cuando un módulo backend (router, service, repository) supera ~1500 LOC en un
solo archivo y contiene sub-dominios identificables, aplicar el playbook de
split documentado en `Skill("proceso-modular-split")`. El patrón clave:

- **Compositor por herencia múltiple, NO `__getattr__`**: el compositor (clase
  monolítica que mantiene API pública previa) hereda de cada sub-service. MRO
  inspeccionable, type checker feliz, IDE autocompleta. `__getattr__` para
  delegación es opaco al tipado y al stack trace.

- **Helpers transversales en clase base, no duplicados entre sub-services**: si
  un helper como `_validar_predio_existe` lo usan ≥80% de sub-services, vive
  en `<modulo>/service_base.py` (`<Modulo>ServiceBase`). Cada sub-service
  hereda de la base. Si solo lo usan 1-2 sub-services, vive en uno de ellos y
  los demás importan por composición (no por herencia).

- **Helper transversal cross-sub-service NO se duplica**: validación que
  aparece en ≥3 sub-services es candidata inmediata a la clase base. La
  duplicación es señal de que el split fue prematuro o de que se perdió el
  helper común durante la migración.

- **Validar a escala**: el patrón se validó a ~20,000 LOC totales en SIGM
  (recaudación ADR-0016 + catastro ADR-0017). Aplicar al primer módulo es
  prudente; antes de aplicar a un tercero, confirmar que el feedback de los
  dos primeros no requiere ajuste al playbook.

Anti-patrones a evitar (las auditorías técnicas NO los detectan):

- Router que importa el compositor cuando existe sub-service específico.
- Router que accede a `servicio._repo` o métodos privados del sub-service.
- Default `None` pasado explícitamente bypasea el default del callee.
- CLAUDE.md y AGENTS.md desincronizados tras el refactor.

Estos los detecta revisión de arquitectura humana o senior, no `nemesis-auditor-swl`.

---

## Reglas de desempate entre principios (conflict resolution)

Los principios de ingeniería pueden entrar en tensión. Cuando dos reglas
correctas en abstracto sugieren caminos opuestos, aplicar las siguientes
heurísticas de desempate. Origen: síntesis adaptada de "Unified Software
Engineering" (M. Ciemborowicz, MIT) más experiencia operativa de SWL.

### Simplicidad vs. modelado rico

- Empezar con el diseño **más simple** que represente honestamente el problema.
- CRUD administrativo y workflows lineales: usar transaction script o
  service layer simple.
- Reglas de negocio complejas, invariantes, ciclos de vida y lenguaje
  específico del dominio: justificar modelado más rico (DDD táctico).
- NO usar patrones de DDD como ceremonia en subdominios genéricos.
- NO aplanar complejidad real del dominio en records pasivos y servicios
  procedurales — eso lo único que hace es desplazar la complejidad al caller.

### Funciones pequeñas vs. módulos profundos

- Funciones pequeñas son una herramienta, no un objetivo en sí mismo.
- Preferir funciones pequeñas cuando clarifican intención, aíslan
  responsabilidad o simplifican testing.
- Evitar cadenas de funciones triviales que solo pasan parámetros (pass-through)
  y obligan al lector a saltar entre archivos para entender una operación.
- Un módulo puede tener implementación interna compleja siempre que su
  interfaz pública sea pequeña, significativa y estable (módulo profundo).

### DRY vs. abstracción prematura

- DRY aplica a duplicación de **conocimiento**, no de texto.
- Centralizar reglas de negocio, validaciones, mappings y cálculos.
- Mantener código similar separado cuando la similitud es **coincidente**
  o cuando la abstracción compartida sería vaga ("regla de tres" antes
  de extraer).
- Tres líneas de código duplicado son mejores que una abstracción
  prematura que después haya que romper.

### Boundaries vs. over-engineering

- Introducir boundaries explícitas alrededor de: volatilidad, sistemas
  externos, persistencia, frameworks, tiempo, aleatoriedad y traducción
  cross-context.
- NO agregar capas que solo reenvían llamadas (forwarding-only layers).
- Toda abstracción debe cumplir **al menos uno** de estos criterios:
  reducir acoplamiento, ocultar complejidad, clarificar ownership, o
  proteger un contrato. Si no cumple ninguno, eliminar la abstracción.

### Consistencia fuerte vs. eventual

- Proteger invariantes que **deben** cumplirse de forma inmediata dentro
  del menor boundary de consistencia útil.
- Default razonable: un aggregate o una transacción local como unidad
  atómica.
- Usar consistencia eventual entre aggregates, servicios o contextos
  cuando la consistencia inmediata no sea un requisito real de negocio.
- Hacer **siempre explícitas** las semánticas de consistencia, staleness,
  conflicto y retry — nunca implícitas.

### Comentarios vs. código auto-documentado

- Mejorar nombres y estructura **antes** de agregar comentarios.
- Comentarios válidos: contratos, invariantes, racional de decisiones
  no-obvias, restricciones legales o regulatorias, asunciones sobre
  protocolos externos.
- Eliminar comentarios que narran código obvio, repiten nombres o
  describen comportamiento obsoleto.

### Refactor vs. preservar comportamiento

- Refactoring debe preservar el comportamiento observable. Sin excepciones.
- Si el comportamiento debe cambiar, mantener el cambio funcional **separado
  del refactor estructural** cuando sea práctico (commits independientes).
- Preferir transformaciones pequeñas y verificables sobre rewrites grandes.

### Cómo aplicar este desempate

Cuando dos principios chocan en una decisión concreta, no inventar
síntesis nuevas — aplicar la heurística arriba según el caso. Si ninguna
aplica, escalar al `arquitecto-swl` con la disyuntiva concreta y dos
opciones evaluadas. Documentar la decisión en un ADR si tiene impacto
estructural.

---

## Checklist arquitectural antes de implementar una feature

- [ ] ¿La decisión requiere un ADR? Si sí, está redactado.
- [ ] ¿El módulo nuevo tiene una interfaz más pequeña que su implementación?
- [ ] ¿Las dependencias fluyen en una sola dirección?
- [ ] ¿Hay separación clara de concerns entre capas?
- [ ] ¿El módulo puede testearse de forma aislada?
- [ ] ¿Se revisaron ADRs existentes para no contradecirlos?
- [ ] ¿No hay duplicación de lógica de negocio entre módulos o capas?
- [ ] Si dos principios entran en tensión, ¿se aplicó la regla de
      desempate correspondiente y la decisión está justificada?
