# ARQUITECTURA COGNITIVA: SISTEMA GRACE (HIBRIDO)
**Version:** 2.0
**Estado:** Enterprise Standard

---

# 1. Filosofia del Sistema: "Alfred Decide, GRACE Transforma"

Para superar las limitaciones de hardware (VPS sin GPU), se adopta una arquitectura de **Orquestacion Hibrida**.

* **ALFRED (El Cuerpo - Local):** Reside en Hostinger (n8n). Es logico, determinista, gestiona credenciales, bases de datos y toma decisiones de enrutamiento.

* **GRACE (El Cerebro - Remoto):** Es efimero y reside en la nube (APIs). Procesa senales complejas (vision, audio, semantica) y devuelve JSON estructurado.

---

# 2. Diagrama de Arquitectura

```
+-----------------------------------------------------------------------+
|                           INFRAESTRUCTURA                              |
+-----------------------------------------------------------------------+
|                                                                        |
|  +------------------+     +------------------+     +------------------+ |
|  |   ALFRED (n8n)   |     |   GRACE (APIs)   |     |   ALMACENAMIENTO | |
|  |                  |     |                  |     |                  | |
|  | - Orquestacion   |<--->| - 18 modulos IA  |     | - Hostinger      | |
|  | - Validacion     |     | - OpenRouter     |     | - S3/GCS         | |
|  | - Logging        |     | - Groq           |     | - Nextcloud      | |
|  | - Decisiones     |     | - RunPod         |     |                  | |
|  +------------------+     +------------------+     +------------------+ |
|           |                       |                       |            |
|           +----------------------++-----------------------+            |
|                                  |                                     |
|  +------------------+     +------------------+     +------------------+ |
|  |   NocoDB/PG      |     |   Key Vault      |     |   SENTINEL       | |
|  |                  |     |                  |     |                  | |
|  | - SYS_LOG        |     | - API Keys       |     | - LIGHT (reglas) | |
|  | - SFE            |     | - Encryption     |     | - DEEP (LLM)     | |
|  | - HST Tags       |     | - Certificados   |     | - Patrones       | |
|  +------------------+     +------------------+     +------------------+ |
|                                                                        |
+-----------------------------------------------------------------------+
```

---

# 3. Mapa de Modulos IA (Implementacion Tecnica)

Basado en la especificacion de 18 microservicios:

## Familia A: VISION (Ojos)
* **Objetivo:** OCR, Analisis de Documentos, Extraccion de Datos.
* **Motor:** GPT-4o (Vision) o Claude 3.5 Sonnet.
* **Flujo:** Alfred envia imagen (base64/URL) -> GRACE analiza -> Devuelve JSON.

## Familia B: VOZ (Oidos)
* **Objetivo:** Transcripcion de reuniones y notas de voz (ASR).
* **Motor:** Whisper Large v3 (Groq API) o Faster Whisper (RunPod).
* **Rendimiento:** Transcripcion a 500x tiempo real.

## Familia D: SEMANTICA (Cortex)
* **Objetivo:** Clasificacion, Resumen, Extraccion de Tareas.
* **Motor:** Meta Llama 3 70B (OpenRouter/Groq).
* **Rendimiento:** Latencia sub-segundo.

## Familia C: IDENTIDAD (Biometria)
* **Estado:** Roadmap Fase 2.
* **Implementacion:** RunPod Serverless para calculo vectorial facial.

---

# 4. Protocolo de Datos e Identidad

Para garantizar la integridad y trazabilidad:

## A. Matricula Interna (TraceID) -> UUID v4
* **Generacion:** Descentralizada (en n8n/Alfred).
* **Funcion:** Clave Primaria en SYS_LOG.
* **Proposito:** Unicidad matematica garantizada.

## B. Huella de Integridad (idempotency_key) -> SHA256
* **Generacion:** `sha256(input_payload)`.
* **Funcion:** Control de Idempotencia.
* **Proposito:** Evitar reprocesamiento y verificar integridad.

---

# 5. El Contrato Comun (S-CONTRACT)

Todo intercambio entre Alfred y GRACE sigue el S-CONTRACT v2.0.

Ver `S-CONTRACT.md` para especificacion completa.

```
+---------------------------------------------------------------------+
|                    PRINCIPIO FUNDAMENTAL                             |
|                                                                      |
|   "Un modulo que no cumple el contrato, no existe para Alfred"       |
+---------------------------------------------------------------------+
```

---

# 6. Flujo de Procesamiento

```
1. ENTRADA
   - Alfred recibe evento (webhook, email, archivo)
   - Genera trace_id y idempotency_key

2. VALIDACION
   - Verifica permisos (player_id + method_hash)
   - Valida schema de entrada

3. ROUTING
   - Carga M-CONTRACT del modulo destino
   - Evalua provider_preference
   - Selecciona proveedor disponible

4. TRANSFORMACION (GRACE)
   - Envia request S-CONTRACT
   - Espera response (respetando timeout)
   - Si falla, activa fallback_chain

5. PERSISTENCIA
   - Guarda resultado en almacenamiento
   - Registra en SYS_LOG

6. AUDITORIA
   - SENTINEL-LIGHT valida conformidad
   - SENTINEL-DEEP analiza errores
   - NOTARIO sella si aplica
```

---

# 7. Infraestructura de Soporte (DECK)

* **Orquestador:** n8n (Docker)
* **Base de Datos:** PostgreSQL 15 + NocoDB
* **Almacenamiento:** Nextcloud / FileBrowser
* **Cache:** Redis
* **Seguridad:** Nginx Proxy Manager + SSL
* **Mail:** Mail-in-a-Box
* **Servicios:** Shlink, Addy.io, Vaultwarden

Ver repositorio `deck` para configuracion detallada.

---

# 8. Documentos Relacionados

| Documento | Descripcion |
|-----------|-------------|
| S-CONTRACT.md | Especificacion del contrato comun |
| MODULOS_IA.md | Catalogo de 18 modulos GRACE |
| SENTINEL.md | Sistema de auditoria |
| KEY_VAULT.md | Gestion de llaves y cifrado |
| NOTARIO.md | Sellado blockchain |
| IMPLEMENTACION.md | Wrappers y ejemplos |

---

**Fin del Documento ARQUITECTURA - Version 2.0**

*Sistema GRACE - "Alfred Decide, GRACE Transforma"*