F04 — Architecture

Phase 4 — Architecture Decision Framework

Objetivo

Disenar la arquitectura dividiendo componentes deterministicos y componentes IA, documentando cada decision critica en un ADR. Cada servicio justifica su nivel de IA (0-3).

1. ADR Template (Architecture Decision Record)

# ADR-NNN: [Titulo de la decision]

## Status
Propuesto | Aceptado | Deprecado | Reemplazado por ADR-XXX

## Contexto
Que situacion motiva esta decision? Que restricciones existen?

## Decision
Que decidimos y por que?

## Consecuencias
- Positivas: que ganamos
- Negativas: que trade-offs aceptamos
- Riesgos: que puede salir mal

## Alternativas Evaluadas
| Opcion | Pros | Contras | Razon de descarte |
|--------|------|---------|-------------------|
| A | ... | ... | ... |
| B | ... | ... | ... |

## AI-Specific Considerations (si aplica)
- Nivel de IA: 0/1/2/3
- Modelo(s): ...
- Costo estimado: $/mes
- Fallback deterministico: si/no, descripcion
- Latencia esperada: p50/p95

2. AI Partition Map

Documento central que muestra que es deterministico y que usa IA:

partition:
  deterministic_components:
    - name: "Auth Service"
      level: 0
      justification: "Logica de autenticacion no necesita IA"
      latency_p95_ms: 50
      cost_per_req_usd: 0

    - name: "Payment Processing"
      level: 0
      justification: "Regulado, debe ser 100% deterministico"
      latency_p95_ms: 200
      cost_per_req_usd: 0

  ai_components:
    - name: "Product Search"
      level: 1  # RAG
      justification: "Busqueda semantica mejora conversion 30%"
      model: "text-embedding-3-large + reranker"
      latency_p95_ms: 400
      cost_per_req_usd: 0.001
      fallback: "Keyword search (Elasticsearch)"

    - name: "Customer Support Agent"
      level: 3  # Autonomous agent
      justification: "Requiere razonamiento multi-paso: consultar CRM, buscar docs, responder"
      model: "Claude Sonnet 4.5"
      tools: ["crm-mcp-server", "knowledge-base-mcp-server", "ticket-mcp-server"]
      latency_p95_ms: 5000
      cost_per_req_usd: 0.03
      fallback: "Escalation to human agent"
      hitl_required: true
      hitl_trigger: "confidence < 70% OR action = refund > $100"

3. Decision Tree — Stack Selection

1. ¿Equipo domina Python? → Backend: FastAPI/Django
   ¿Equipo domina JS/TS? → Backend: Hono/NestJS/Next.js
   ¿Equipo domina Go? → Backend: Chi/Echo (si no es AI-heavy)

2. ¿Compliance requiere on-premise? → Infra: Container/K8s on-prem
   ¿Budget < $100/mes? → Infra: Serverless (Cloudflare Workers, Vercel)
   ¿Necesita GPU? → Infra: Container con GPU (ECS, GKE)
   ¿Default? → Infra: PaaS (Railway, Render, Cloud Run)

3. ¿Multiples agentes coordinados? → Orquestacion: LangGraph (stateful cycles)
   ¿Tareas estructuradas multi-paso? → Orquestacion: CrewAI
   ¿Simple prompt chain? → Orquestacion: Custom (sin framework)

4. ¿Necesita vector search? → DB: PostgreSQL + pgvector (default)
   ¿Volumen masivo de vectors? → DB: Qdrant / Pinecone

4. Trade-off Matrix

Para cada decision significativa, evaluar:

Criterio	Peso	Opcion A	Opcion B	Opcion C
Costo mensual	25%	$50	$200	$500
Latencia p95	20%	100ms	50ms	30ms
Skill del equipo	20%	Alto	Medio	Bajo
Compliance	15%	OK	OK	Requiere ajuste
Escalabilidad	10%	Auto-scale	Manual	Auto-scale
Vendor lock-in	10%	Bajo	Medio	Alto
Score ponderado	100%	8.2	7.5	6.1

5. NFR (Non-Functional Requirements) Template

nfr:
  latency:
    api_p50_ms: 200
    api_p95_ms: 500
    llm_p50_ms: 1500
    llm_p95_ms: 3000
  availability:
    target: "99.5%"
    rto_minutes: 30
    rpo_minutes: 60
  cost:
    monthly_budget_usd: 500
    cost_per_llm_request_max_usd: 0.05
    daily_cost_alert_threshold_usd: 25
  security:
    owasp_llm_top10: "required"
    owasp_asi_top10: "required"
    data_classification: "required"
    pen_test_frequency: "quarterly"
  scalability:
    concurrent_users: 100
    requests_per_second: 50
    auto_scaling: true

6. Checklist de Salida — Gate 4

AI Partition Map documentado (que es deterministico, que es IA)
ADR de stack selection (adr_001_stack_selection.md)
ADR por cada decision de nivel AI > 0
Fallback strategy definida para cada componente AI
NFR documentados con targets cuantificables
Deployment track seleccionado con justificacion
Cost model estimado por componente

Entregables minimos por track

Artefacto	Solo	Lean	Full
`adr_001_stack_selection.md`	Requerido	Requerido	Requerido
`ai_partition_map.yaml`	Informal	YAML	YAML + diagrama
ADRs adicionales	No requerido	Por componente AI	Todas las decisiones
Trade-off matrix	No requerido	Informal	Formal
NFR document	En config	YAML basico	YAML + monitoring

Referencias

CORE_F04_Patrones_Agenticos.md — patrones de agentes
CORE_F04_Stack_Selection_Framework.md — criterios de stack
CORE_F04_Software_Survival_Assessment.md — assessment de supervivencia
Schema: scripts/schemas/ai_cost_model.schema.json
Skill: /f04_architecture

AI-First Engineering Framework v6.5 — Phase 4: AI/Deterministic Architecture Design