┌─────────────────────────────────────────────────────────────────────────────┐
│                              PACKET (App móvil)                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
           ┌────────────────────────────┼────────────────────────────┐
           │                            │                            │
           ▼                            ▼                            ▼
  ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
  │     CLARA       │        │    MARGARET     │        │  ALFRED/JARED   │
  │   (DECK log)    │        │   (CORP log)    │        │(flujo predefinido)│
  │   inmutable     │        │   inmutable     │        │                 │
  └────────┬────────┘        └────────┬────────┘        └────────┬────────┘
           │                          │                          │
           └──────────────────────────┴──────────────────────────┘
                                      │
                                      ▼
                               ┌─────────────┐
                               │    MASON    │
                               │(enriquecer) │
                               └──────┬──────┘
                                      │
                                      ▼
                               ┌─────────────┐
                               │   FELDMAN   │
                               │(consolidar) │
                               └─────────────┘

Función

Recibe contenedor de PACKET
Envía archivos a R2
Registra en PostgreSQL:
- Metadata del contenedor
- Ubicación de archivos en R2
NO añade información
NO procesa
NO modifica

Comparación

Componente	Servidor	Tipo	Función
CLARA	DECK	Input suelto	Log de entrada personal
MARGARET	CORP	Input suelto	Log de entrada empresarial
ALFRED	DECK	Flujo predefinido	Cadenas de pasos conocidos
JARED	CORP	Flujo predefinido	Cadenas de pasos + NOTARIO

Identificador

h_instancia = SHA-256(seed único de DECK)

Mismo hash para:

Autenticación: X-Auth-Key: {h_instancia}
Biblioteca privada: h_biblioteca = h_instancia
Prefijo R2: {endpoint}/{h_instancia}/...

API

Recepción

POST /ingest
X-Auth-Key: {h_instancia}
Content-Type: application/json

{
  "hash": "fc2fae65...",
  "titulo": "opcional",
  "descripcion": "opcional",
  "etiquetas": ["h_maestro1", "h_maestro2"],
  "gps": {"lat": 43.36, "long": -8.41},
  "archivos": [...]
}

Respuestas

200: {"ok": true, "id": 1001}
409: {"error": "hash_exists"}
401: {"error": "unauthorized"}

Estructura de Datos

CLARA registra contenedores con la siguiente estructura (ver esquema completo):

{
  "id": "uuid-contenedor",
  "h_instancia": "sha256-instancia",
  "archivo_hash": "sha256-archivo",

  "origen": {
    "dispositivo": "uuid-dispositivo",
    "app_version": "1.0.0",
    "timestamp_captura": "2025-01-15T10:30:00Z",
    "geolocalizacion": {"lat": 41.38, "lon": 2.17, "precision_m": 10}
  },

  "archivo": {
    "tipo": "image/jpeg",
    "categoria": "imagen",
    "size_bytes": 2048576,
    "dimensiones": {"ancho": 1920, "alto": 1080}
  },

  "tags": [
    {"h_maestro": "sha256", "grupo": "hst", "nombre": "Factura", "confianza": 1.0}
  ],

  "estado": {
    "actual": "en_clara",
    "historial": [{"paso": "clara", "entrada": "...", "procesado_por": "clara-service"}]
  }
}

Secciones que CLARA recibe de PACKET:

identificacion: id, h_instancia, archivo_hash
origen: dispositivo, app_version, timestamp, geolocalizacion
archivo: metadata tecnica
tags: etiquetas iniciales

Secciones que CLARA NO toca:

extraccion: la anade servicio externo despues
enriquecimiento: la anade usuario en MASON
bloque: la anade FELDMAN al consolidar

Tabla PostgreSQL

CREATE TABLE clara_log (
    id              BIGSERIAL PRIMARY KEY,
    h_instancia     VARCHAR(64) NOT NULL,
    h_entrada       VARCHAR(64) NOT NULL,
    contenedor      JSONB NOT NULL,
    r2_paths        JSONB,
    created_at      TIMESTAMP DEFAULT NOW()
);

-- Inmutable: sin updated_at
CREATE INDEX idx_clara_instancia ON clara_log(h_instancia);
CREATE INDEX idx_clara_entrada ON clara_log(h_entrada);
CREATE INDEX idx_clara_estado ON clara_log((contenedor->>'estado'->>'actual'));

Inmutabilidad

Registros NUNCA se modifican
Archivos en R2 NUNCA se mueven
Las correcciones se hacen en MASON

Arquitectura Completa

Ver documentación en contratos-comunes/architecture

Repositorios Relacionados

Repo	Rol
margaret	Equivalente para CORP
alfred	Flujos predefinidos DECK
mason	Enriquecimiento
feldman	Consolidación
sentinel	Auditoría
packet	App móvil

Implementación

Este repositorio contiene la implementación completa del servicio CLARA:

Archivos principales

app.py: Servicio Flask con API REST
Dockerfile: Imagen Docker del servicio
docker-compose.yml: Orquestación con PostgreSQL
init.sql: Schema de base de datos
requirements.txt: Dependencias Python
test_clara.sh: Suite de tests automatizados
DEPLOYMENT.md: Guía de despliegue completa

Tecnologías

Backend: Flask + Gunicorn
Base de datos: PostgreSQL 15 con JSONB
Storage: Cloudflare R2 (compatible S3)
Contenedores: Docker + Docker Compose
Testing: Bash + curl + jq

Inicio rápido

# 1. Configurar credenciales
cp .env.example .env
nano .env

# 2. Iniciar servicios
docker-compose up -d

# 3. Verificar
curl http://localhost:5051/health

# 4. Ejecutar tests
./test_clara.sh

Ver DEPLOYMENT.md para instrucciones completas.

Estado del servicio

✅ Implementación completa
✅ Tests automatizados
✅ Docker ready
⏳ Pendiente despliegue a DECK (72.62.1.113)
⏳ Pendiente integración con PACKET

Componente del sistema TZZR - Actualizado 2025-12-23