fit-boilerplate-wox/docs/architecture-patterns.md

Architecture Patterns

Árbol de decisión que usa el subagente wxo-architect cuando arrancás un caso nuevo. Te llevo pregunta por pregunta.

---

Pregunta 1 — ¿Cuántos dominios distintos toca el caso?

Un "dominio" = una superficie funcional bien delimitada (identidad, operaciones, RRHH, finanzas, CRM, etc.).

• 0–1 dominio → 1 agente solo. Salí del árbol con la Topología Single.
• 2–5 dominios → N specialists + 1 orchestrator. Topología Multi-Specialist (estilo Cotemar).
• 6+ dominios → 2 capas: sub-orchestrators temáticos. Topología Multi-Capa.

---

Pregunta 2 — ¿El flujo es lineal o ramificado?

• Lineal y conocido (caso entra → A → B → C → D → resultado, siempre el mismo orden): aplicá Patrón Meta-Tool (estilo Dun). Una sola tool run_full_case que el backend orquesta internamente. El agente invoca esa tool y listo.
• Ramificado (el agente decide qué hacer según el input): N tools individuales, agente razona. Cuidado con recursion_limit=30 (ver known-issues.md).
• Mixto: parte lineal en meta-tool, parte ramificada en tools individuales. Es lo más común en casos reales.

---

Pregunta 3 — ¿Cada agente necesita razonar sobre procedimientos escritos?

Para cada agente, preguntate: "¿el LLM necesita citar un runbook para decidir bien?"

• Sí (procedural): este agente tiene KB con runbooks. Estilo Cotemar AD specialist.
• No (API-driven): este agente no tiene KB. El system prompt describe qué hace, las tools describen las acciones disponibles. Estilo Dun QA Studio.
• Mixto: KB para el "qué" + tools para el "cómo". Solo cuando los procedimientos son largos y variables.

---

Pregunta 4 — ¿Qué tipo de tools va a tener cada agente?

Por cada dominio, elegí el tipo de tool:

Opción A — OpenAPI (preferido si tenés backend propio)

Cuándo: tu solución incluye un backend (FastAPI, Express, lo que sea) que ya define endpoints REST.

Pros:

• Una sola fuente de verdad (el spec)
• ADK importa todo en un comando
• Cambios al backend = re-import del spec, no toques YAML de tool

Pattern del template (estilo Dun):

• Backend expone /orchestrate-tools-spec.json (endpoint filtrado)
• Filtra el openapi.json a una allowlist PUBLIC_TOOLS
• Fuerza description y security per-operation
• Patch del servers[0].url en deploy time según env

Ver wxo/tools/openapi/_backend_filter_endpoint.py para el template.

Opción B — Python @tool (preferido para mocks/PoC)

Cuándo: estás prototipando, mocks externos, lógica simple por tool, sin backend que valga la pena mantener.

Pros:

• Rápido de escribir, una función = una tool
• Fácil de testear con pytest
• Bajo overhead

Pattern del template (estilo Cotemar):

• Una función @observable_tool(name="x") por endpoint mockeado
• Lee BASE_URL del environment de su connection
• requests.post(...) y devuelve dict
• _compat.py inline al inicio del archivo

Ver wxo/tools/python/_template_tools.py.

Opción C — MCP (preferido si el sistema lo expone)

Cuándo: el sistema externo (HubSpot, Outline, una DB con MCP server, GitHub vía MCP, etc.) ya expone un MCP server.

Pros:

• Trae types + permisos del sistema
• Mantenido por el vendor
• Una sola connection MCP da acceso a todas las tools del server

Pattern del template:

• Una connection.yaml de tipo MCP apuntando al server
• ADK descubre las tools y las hace disponibles al agente
• Ver wxo/tools/mcp/_template_mcp_connection.yaml

Decisión

Situación	Recomendación
Es PoC, mocks externos	Python @tool
Tengo backend propio (FastAPI/Express)	OpenAPI
Conecto a SaaS con MCP server	MCP
Conecto a SaaS sin MCP server	OpenAPI (escribís el spec a mano) o Python
Mezcla	Cada agente puede usar más de uno

---

Pregunta 5 — ¿Web layer: cuál stack?

Dos happy-paths probados:

Stack A — FastAPI + HTMX + Jinja (default)

Cuándo: demos, PoCs, control planes, kanbans, paneles operativos Pros: SSR, sin build step, polling con hx-trigger es trivial, una sola persona la mantiene Contras: menos interactivo, menos componibilidad Origen: estilo Cotemar (UNUS Kanban + Control Plane)

Stack B — FastAPI + React + Vite + Tailwind + zustand

Cuándo: app productiva con varios usuarios, mucha interacción, UI rica Pros: ecosistema React, lazy loading, state management decente Contras: build step, más superficie de mantenimiento Origen: estilo Dun (QA Studio)

Decisión

• Demo / interno / PoC → Stack A
• Producción / multi-usuario / app rica → Stack B
• Híbrido → Stack A para dashboards, Stack B para la app principal, unidos por reverse proxy

El template trae Stack A en web/_default_fastapi_htmx/. Stack B viene documentado pero no implementado (el subagente Claude web-layer-builder te lo arma según el caso).

---

Pregunta 6 — ¿Deploy: dónde corre esto?

Tres opciones soportadas:

Target	Para qué	Ver
Coolify (FIT default)	Demos + PoCs productivos en *.fitlabs.dev	docs/deployment-guide.md
Docker compose local	Dev / testing	docs/INSTRUCCIONES.md
K8s / Cloud Run / otro	Producción del cliente	docs/deployment-guide.md § "Other targets"

---

Topologías resultantes

Topología Single (1 agente)

[user] → [agente único] ──tools──→ [sistema externo]
                       └──KB──→ [opcional]

Topología Multi-Specialist (Cotemar pattern)

                  ┌──→ ad_specialist     ──tools──→ AD
[user] → [N1] ────┼──→ ops_specialist    ──tools──→ Ops
        (orch)    └──→ rrhh_specialist   ──tools──→ HR
            │
            └─escalate→ runbook 03 (KB propia)

Topología Meta-Tool (Dun pattern)

[user] → [agente único] ──run_full_case(id)──→ [backend orquesta:
                                                  step 1, step 2, ...
                                                  write_audit cada paso]

Topología Multi-Capa (>5 dominios)

                          ┌─→ [sub-orch identidad] ─→ ad, hr, vendors
[user] → [super-orch] ────┤
                          ├─→ [sub-orch ops]       ─→ dynatrace, k8s, db
                          └─→ [sub-orch finanzas]  ─→ sap, billing

---

Cuando dudes

• ¿1 agente o varios? → Si los dominios son disjuntos, varios. Si todo es del mismo dominio, uno.
• ¿KB o no? → Si hay procedimiento escrito que el LLM debe seguir literal, sí. Si no, no.
• ¿OpenAPI o Python? → ¿Tenés backend? OpenAPI. ¿Mocks? Python.
• ¿Meta-tool o tools sueltas? → ¿El flujo es lineal y conocido? Meta-tool. ¿El agente decide? Sueltas.

Cuando dudes, arrancá con menos. Es más fácil splittear un agente en dos que mergear dos en uno.