# Forja — Arquitectura técnica

> Documento vivo con las decisiones técnicas.

## Visión general

Forja es un **único servicio FastAPI** (:8000):
- Todo el dominio de gobierno, runtime LangGraph, guardrails y persistencia.
- UI embebida (HTMX) para uso humano + API REST completa bajo `/api`.

## Diagrama

```
┌────────────────────────────────────────────────────────────┐
│                     forja-core :8000                        │
│  UI HTMX (humanos)  +  REST API (/api)  +  dominio completo │
│                                                             │
│   LLM (strategy)  │  Guardrails (strategy)  │  LangGraph    │
│                   │                         │  + checkpoints│
└────────────────────────────────────────────────────────────┘
```

## Patrones aplicados

- **Strategy / Plugin**: `LLMProvider`, `GuardrailEngine`, `AgentRegistry`,
  `PolicyStore` son `Protocol`s con varias implementaciones intercambiables
  vía factory que lee `Settings`.
- **Configuration over code**: agentes y políticas como YAML versionados;
  cambios sin redeploy.
- **Fail-closed por defecto**: errores en validadores cuentan como bloqueo.
- **Trazabilidad obligatoria**: `trace_id` UUID propagado por
  middleware → structlog → API → JSONL.

## Persistencia

| Capa | Tecnología | Por qué |
|---|---|---|
| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). |
| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. |
| Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. |
| Logs de ejecuciones | JSONL append-only | Idem. |
| Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). |

## HITL — Patrón

Se usa la API dinámica `interrupt(payload)` de LangGraph ≥0.2 dentro del
nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo
(`risk_score >= threshold` o `requires_approval=True`). El cliente envía
`Command(resume={"approved_action_ids": [...]})` vía
`POST /api/executions/{trace_id}/approve`.

## Observabilidad

- `structlog` con renderer JSON.
- Middleware FastAPI inyecta `X-Trace-Id` y bind-ea contexto.
- Cada nodo del grafo añade un step a `decision_path` con `duration_ms`.

## Errores

- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego
  `status=failed`.
- Validador: `fail_closed` por defecto.
- Schema mismatch en LLM output: 1 retry, luego `failed`.
- Checkpoint corrupto: 500 explícito (sin auto-recovery).

## Decisiones pospuestas

Ver [`docs/futuro.md`](docs/futuro.md).