Arquitectura técnica — Enterprise AI Platform (MVP)

1. Idea central

Una plataforma común de IA en Azure que:

• Expone agentes y APIs a través de Azure API Management
• Orquesta con Microsoft Foundry / Agent Service
• Integra datos vía REST (Finanzas estructurado) y MCP (RR.HH. documental + opcional proveedores)
• Aplica gobierno: Entra ID, RBAC, Key Vault, reglas determinísticas, auditoría, observabilidad

Las apps Finance y HR son clientes de la plataforma; no son silos de IA.

Estado as-built (Finance DEV): portal + API en Container Apps, reglas + HITL + DI + Foundry agent con guardrails, Entra apps creadas, APIM opt-in en Terraform. HR sigue planificado.

Guía de onboarding: getting-started.md · Identidad: entra-apim-finance.md.

---

1b. Runtime Finance (como está desplegado)

flowchart TB
  subgraph Browser
    UI["finance-web<br/>HITL · PDF · Chat · i18n"]
  end

  subgraph ACA["Container Apps · mexicocentral"]
    WEB["ca-eai-finance-web-dev"]
    API["ca-eai-finance-api-dev"]
    MCP["ca-eai-mcp-sup-dev"]
  end

  subgraph Platform
    APIM["APIM Developer<br/>enable_apim"]
    ENTRA["Entra SPA + API"]
    FOUNDRY["Foundry eai-finance-agent v3"]
  end

  subgraph PaaS
    SQL[(Azure SQL)]
    BLOB[(Blob invoices)]
    DI[Document Intelligence]
    AI[App Insights]
  end

  UI --> WEB
  WEB -->|"proxy /api/finance<br/>Bearer"| APIM
  WEB -.->|"si APIM off"| API
  APIM --> API
  ENTRA --> UI
  ENTRA --> APIM
  API --> SQL
  API --> BLOB
  API --> DI
  API --> FOUNDRY
  FOUNDRY -->|"function tools"| API
  FOUNDRY -.-> MCP
  MCP --> SQL
  API --> AI
  WEB --> AI

Proxy Next: el navegador no llama al FQDN del API directamente; usa rutas /api/finance/*. El servidor reenvía a APIM_GATEWAY_URL o FINANCE_API_BASE_URL, con Authorization y x-correlation-id.

PDF: el visor hace GET autenticado y muestra un blob URL (no depende de HEAD).

Chat: chat_guardrails en API → Foundry + tool loop local (SQL) si el mensaje está en dominio AP.

---

2. Diagrama lógico (Mermaid)

flowchart TB
  subgraph Apps["Aplicaciones de negocio"]
    FIN["Finance App<br/>Next.js"]
    HR["HR App<br/>Next.js"]
  end

  subgraph Platform["Plataforma Empresarial IA"]
    APIM["Azure API Management<br/>Gateway · Auth · Policies · Correlation"]
    FOUNDRY["Microsoft Foundry<br/>Finance Agent · HR Agent"]
    RULES["Rule Engine<br/>determinístico"]
    AUDIT["Audit Service<br/>SQL + App Insights"]
  end

  subgraph SecObs["Gobierno"]
    ENTRA["Microsoft Entra ID"]
    KV["Key Vault"]
    AI["App Insights + Log Analytics"]
  end

  subgraph FinanceDomain["Dominio Finanzas"]
    BLOB_F["Blob Storage<br/>facturas PDF"]
    DI["Document Intelligence"]
    PROC["Invoice Processor<br/>Function / ACA"]
    SQL["Azure SQL<br/>suppliers · POs · invoices · rules · audit"]
    API_F["Finance API<br/>REST tools"]
    MCP_S["MCP Suppliers<br/>opcional"]
  end

  subgraph HRDomain["Dominio RR.HH."]
    BLOB_H["Blob Storage<br/>políticas PDF"]
    SEARCH["Azure AI Search<br/>RAG"]
    MCP_H["MCP Server HR"]
    API_H["HR API"]
  end

  FIN --> APIM
  HR --> APIM
  APIM --> FOUNDRY
  APIM --> API_F
  APIM --> API_H
  ENTRA --> APIM
  ENTRA --> FIN
  ENTRA --> HR
  KV --> API_F
  KV --> MCP_H
  FOUNDRY --> AI
  API_F --> AI
  AUDIT --> SQL
  AUDIT --> AI

  FIN --> BLOB_F
  BLOB_F --> PROC
  PROC --> DI
  PROC --> FOUNDRY
  FOUNDRY -->|REST vía APIM| API_F
  FOUNDRY -->|MCP| MCP_S
  API_F --> SQL
  API_F --> RULES
  RULES --> SQL
  MCP_S --> SQL

  FOUNDRY -->|MCP| MCP_H
  MCP_H --> SEARCH
  SEARCH --> BLOB_H
  API_H --> MCP_H

---

3. Flujo end-to-end — Finanzas

sequenceDiagram
  actor U as Finance.User / Reviewer
  participant App as Finance App
  participant APIM as APIM
  participant Blob as Blob Storage
  participant Proc as Invoice Processor
  participant DI as Document Intelligence
  participant Agent as Invoice / Finance Agent
  participant REST as Finance API tools
  participant MCP as MCP Suppliers
  participant Rules as Rule Engine
  participant Audit as Audit Store

  U->>App: Sube factura PDF
  App->>APIM: POST /api/finance/invoices
  APIM->>Blob: Guarda PDF
  APIM->>Audit: InvoiceUploaded + correlationId
  Blob->>Proc: Evento / trigger
  Proc->>DI: Analyze invoice
  DI-->>Proc: Campos extraídos
  Proc->>Audit: InvoiceDataExtracted
  Proc->>Agent: Start Invoice execution
  Agent->>MCP: validate_supplier()
  MCP-->>Agent: VALID / INVALID
  Agent->>REST: get_purchase_order()
  REST-->>Agent: PO data
  Agent->>REST: validate_invoice_amount() / check_duplicate()
  Agent->>Rules: evaluate_finance_policy()
  Rules-->>Agent: FIN-00x PASS/FAIL (determinístico)
  alt Excepción
    Agent->>Audit: HumanReviewRequested
    U->>App: Aprueba / Rechaza
    App->>APIM: POST approve/reject
    APIM->>Audit: HumanDecision
  else Sin excepción
    Agent->>Audit: Approved automático
  end

---

4. Flujo end-to-end — RR.HH.

sequenceDiagram
  actor U as HR.User
  participant App as HR App
  participant APIM as APIM
  participant Agent as HR Agent
  participant MCP as MCP HR Server
  participant Search as Azure AI Search

  U->>App: "¿Política de trabajo remoto?"
  App->>APIM: POST /api/hr/chat
  APIM->>Agent: Chat + user context
  Agent->>MCP: search_hr_policy / get_policy
  MCP->>Search: Hybrid / semantic query
  Search-->>MCP: Chunks + source
  MCP-->>Agent: Contenido + citas
  Agent-->>App: Respuesta + fuente documental

---

5. Separación LLM vs determinístico

Capacidad	Responsable	Motivo
Extraer campos de PDF	Document Intelligence + validación	Especializado / estable
Explicar resultado al usuario	LLM (Finance Agent)	Lenguaje natural
Chat y clasificación no crítica	LLM	UX
Reglas FIN-001…FIN-005	Rule Engine (código + SQL)	No negociable
Aprobar/rechazar por política	Reglas + HITL	Compliance
Acceso a datos	Tools REST/MCP únicamente	El LLM no toca DB

---

6. Modelo de seguridad (MVP)

flowchart LR
  User --> Entra
  Entra -->|OIDC token| App
  App -->|Bearer + scopes| APIM
  APIM -->|validate-jwt| Backend
  Backend -->|Managed Identity| SQL
  Backend -->|Managed Identity| Blob
  Backend -->|Managed Identity| KV
  Agent -->|function tools en host API| Backend

Autenticación (Entra) vs autorización (app/APIM): ver entra-apim-finance.md.

Control	Estado MVP
Login portal MSAL	Implementado (demo si no hay client id)
JWT en APIM	Implementado cuando enable_apim=true
Grupos Reviewer/User	Creados; assignment required = opcional
Solo Reviewer aprueba HITL	Hecho (API JWT groups + APIM 403 + UI)
Acceso portal User|Reviewer	Hecho (AccessDenied + APIM + API middleware)
ACA API solo vía APIM	Hecho (DEV) — ingress IP allowlist = IPs públicas APIM; FQDN ACA → 403. external_enabled=false requiere VNet (CAE + APIM); hoy ambos sin VNet

Aislamiento de agentes - Finance Agent: solo tools finance (REST + MCP suppliers opcional). - HR Agent: solo tools MCP HR / Search (futuro). - Instructions Foundry + guardrails API + scopes APIM.

Modelo enterprise futuro: VNET, Private Endpoints, APIM internal (external_enabled=false), OpenAI privado, Private DNS.

---

7. Modelo de datos (resumen)

SQL (Finanzas + auditoría funcional)
Suppliers, PurchaseOrders, Invoices, InvoiceLines, BusinessRules, RuleExecutions, AgentExecutions, ToolExecutions, HumanDecisions, TokenUsage (FinOps).

Blob
invoices/, hr-policies/.

AI Search
Índice hr-policies con chunks, metadata (source, policy_type, page).

Detalle de tablas: ver data-model.md.

---

8. Decisiones arquitectónicas (ADRs cortos)

ID	Decisión	Elección MVP	Alternativa descartada
ADR-01	Gateway	Azure APIM Developer	App Gateway solo (sin políticas API)
ADR-02	Orquestación agentes	Foundry Agent Service	LangChain self-host completo
ADR-03	Backend	Python FastAPI	.NET / Node (válidos, unificar en uno)
ADR-04	Compute	Container Apps	AKS (overkill)
ADR-05	Eventos invoice	Function + Blob trigger (simple)	Durable / Service Bus (fase 2)
ADR-06	Reglas	Motor propio SQL/código	LLM decide (prohibido)
ADR-07	HR tools	MCP Server real	Solo REST (no demostraría MCP)
ADR-08	IaC	Terraform	Portal manual
ADR-09	Foundry	Un proyecto, dos agentes	Dos proyectos (más complejo)

---

9. Riesgos

Riesgo	Impacto	Mitigación
Foundry Agent / MCP en preview en región	Alto	Marcar preview; fallback: orquestación FastAPI + tools OpenAI function calling
Cuota OpenAI insuficiente	Alto	Pedir aumento temprano; cachear demos
APIM costo / lead time	Medio	Empezar con APIs públicas + Entra; APIM en iteración 3
Document Intelligence calidad en PDFs ficticios	Medio	Plantillas claras + post-validación de schema
Scope creep (Power BI, VNET, multi-agent)	Alto	Criterio de éxito del prompt como contrato

---

10. Componente a implementar primero

1. Contratos + modelo SQL + Rule Engine + Audit (sin Azure aún, Docker SQL opcional)
2. Finance API (upload mock → extract mock → rules → HITL)
3. MCP HR + documentos
4. Frontends demo
5. Wiring Azure (DI, Search, Foundry, APIM) + Terraform

Ver backlog.md y iteration-plan.md.