docs(v5): Complete system documentation
Comprehensive documentation for TZZR system v5 including: - 00_VISION: Glossary and foundational philosophy - 01_ARQUITECTURA: System overview and server specs - 02_MODELO_DATOS: Entity definitions and data planes (T0, MST, BCK) - 03_COMPONENTES: Agent docs (CLARA, MARGARET, FELDMAN, GRACE) - 04_SEGURIDAD: Threat model and secrets management - 05_OPERACIONES: Infrastructure and backup/recovery - 06_INTEGRACIONES: GPU services (RunPod status: blocked) - 99_ANEXOS: Repository inventory (24 repos) Key findings documented: - CRITICAL: UFW inactive on CORP/HST - CRITICAL: PostgreSQL 5432 exposed - CRITICAL: .env files with 644 permissions - RunPod workers not starting (code ready in R2) - Infisical designated as single source of secrets (D-001) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
ARCHITECT
311
03_COMPONENTES/agentes/clara-margaret.md
Normal file
311
03_COMPONENTES/agentes/clara-margaret.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# CLARA y MARGARET - Agentes de Ingesta
|
||||
|
||||
**Versión:** 5.0
|
||||
**Fecha:** 2024-12-24
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Aspecto | CLARA | MARGARET |
|
||||
|---------|-------|----------|
|
||||
| Servidor | DECK (72.62.1.113) | CORP (92.112.181.188) |
|
||||
| Puerto | 5051 | 5051 |
|
||||
| Dominio | Personal | Empresarial |
|
||||
| Base de datos | tzzr | corp |
|
||||
| Tabla log | clara_log | margaret_log |
|
||||
| Bucket R2 | deck | corp |
|
||||
| Estado | Operativo | Operativo |
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
PACKET (App móvil)
|
||||
│
|
||||
│ POST /ingest
|
||||
│ Content-Type: multipart/form-data
|
||||
│ X-Auth-Key: {h_instancia}
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ CLARA (Personal) / MARGARET (Corp) │
|
||||
│ │
|
||||
│ 1. Validar h_instancia │
|
||||
│ 2. Calcular h_entrada (SHA-256) │
|
||||
│ 3. Subir archivos a R2 │
|
||||
│ 4. Insertar en log (inmutable) │
|
||||
│ 5. Estado: 'recibido' │
|
||||
│ 6. Responder con h_entrada │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
ALFRED / JARED (siguiente paso)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpoint de Ingesta
|
||||
|
||||
### Request
|
||||
|
||||
```http
|
||||
POST /ingest HTTP/1.1
|
||||
Host: deck.example.com:5051
|
||||
Content-Type: multipart/form-data
|
||||
X-Auth-Key: {h_instancia}
|
||||
|
||||
--boundary
|
||||
Content-Disposition: form-data; name="tipo"
|
||||
|
||||
documento
|
||||
--boundary
|
||||
Content-Disposition: form-data; name="archivo"; filename="doc.pdf"
|
||||
Content-Type: application/pdf
|
||||
|
||||
{binary data}
|
||||
--boundary--
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"h_entrada": "a1b2c3d4e5f6...",
|
||||
"estado": "recibido",
|
||||
"timestamp": "2024-12-24T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cálculo de h_entrada
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
import json
|
||||
|
||||
def calcular_h_entrada(h_instancia, tipo, contenido_bytes, timestamp):
|
||||
"""
|
||||
Calcula el hash único de entrada.
|
||||
|
||||
h_entrada = SHA-256(h_instancia:tipo:sha256(contenido):timestamp)
|
||||
"""
|
||||
hash_contenido = hashlib.sha256(contenido_bytes).hexdigest()
|
||||
|
||||
data = f"{h_instancia}:{tipo}:{hash_contenido}:{timestamp}"
|
||||
|
||||
return hashlib.sha256(data.encode()).hexdigest()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schema: clara_log / margaret_log
|
||||
|
||||
```sql
|
||||
CREATE TABLE clara_log (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
h_entrada VARCHAR(64) UNIQUE NOT NULL,
|
||||
h_instancia VARCHAR(64) NOT NULL,
|
||||
tipo VARCHAR(50) NOT NULL,
|
||||
contenido_url TEXT, -- locker://deck/{h_entrada}/archivo
|
||||
contenido_hash VARCHAR(64), -- SHA-256 del contenido
|
||||
metadata JSONB,
|
||||
estado VARCHAR(20) DEFAULT 'recibido',
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
processed_at TIMESTAMPTZ,
|
||||
processed_by VARCHAR(50) -- 'alfred' o 'manual'
|
||||
);
|
||||
|
||||
-- margaret_log tiene schema idéntico
|
||||
CREATE TABLE margaret_log (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
h_entrada VARCHAR(64) UNIQUE NOT NULL,
|
||||
h_instancia VARCHAR(64) NOT NULL,
|
||||
tipo VARCHAR(50) NOT NULL,
|
||||
contenido_url TEXT,
|
||||
contenido_hash VARCHAR(64),
|
||||
metadata JSONB,
|
||||
estado VARCHAR(20) DEFAULT 'recibido',
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
processed_at TIMESTAMPTZ,
|
||||
processed_by VARCHAR(50)
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados del Log
|
||||
|
||||
| Estado | Descripción |
|
||||
|--------|-------------|
|
||||
| recibido | Ingesta completada, pendiente procesamiento |
|
||||
| procesando | ALFRED/JARED está procesando |
|
||||
| enviado_mason | Enviado a MASON para enriquecimiento |
|
||||
| consolidado | Procesado por FELDMAN |
|
||||
| error | Error en procesamiento |
|
||||
|
||||
---
|
||||
|
||||
## Almacenamiento en R2
|
||||
|
||||
### Estructura de URLs
|
||||
|
||||
```
|
||||
locker://deck/{h_entrada}/archivo.ext
|
||||
locker://corp/{h_entrada}/archivo.ext
|
||||
```
|
||||
|
||||
### Implementación
|
||||
|
||||
```python
|
||||
import boto3
|
||||
|
||||
def subir_a_r2(bucket, h_entrada, archivo_bytes, filename):
|
||||
"""Sube archivo a Cloudflare R2."""
|
||||
|
||||
s3 = boto3.client(
|
||||
's3',
|
||||
endpoint_url='https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com',
|
||||
aws_access_key_id=R2_ACCESS_KEY,
|
||||
aws_secret_access_key=R2_SECRET_KEY
|
||||
)
|
||||
|
||||
key = f"{h_entrada}/{filename}"
|
||||
|
||||
s3.put_object(
|
||||
Bucket=bucket,
|
||||
Key=key,
|
||||
Body=archivo_bytes
|
||||
)
|
||||
|
||||
return f"locker://{bucket}/{key}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validación de h_instancia
|
||||
|
||||
```python
|
||||
def validar_instancia(h_instancia):
|
||||
"""
|
||||
Valida que h_instancia exista y esté activa.
|
||||
|
||||
TODO: Implementar tabla de instancias activas.
|
||||
Actualmente: Validación básica de formato.
|
||||
"""
|
||||
if not h_instancia:
|
||||
return False
|
||||
|
||||
if len(h_instancia) != 64:
|
||||
return False
|
||||
|
||||
# TODO: Consultar tabla de instancias
|
||||
return True
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Ingesta Soportados
|
||||
|
||||
| Tipo | Descripción | Extensiones |
|
||||
|------|-------------|-------------|
|
||||
| documento | Documentos | pdf, doc, docx |
|
||||
| imagen | Imágenes | jpg, png, gif |
|
||||
| audio | Audio | mp3, wav, m4a |
|
||||
| video | Video | mp4, mov |
|
||||
| texto | Texto plano | txt, md |
|
||||
| json | Datos estructurados | json |
|
||||
|
||||
---
|
||||
|
||||
## Configuración
|
||||
|
||||
### Variables de Entorno
|
||||
|
||||
```bash
|
||||
# CLARA (.env en /opt/clara/)
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=tzzr
|
||||
DB_USER=clara
|
||||
DB_PASSWORD=****
|
||||
|
||||
R2_ENDPOINT=https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
R2_ACCESS_KEY=****
|
||||
R2_SECRET_KEY=****
|
||||
R2_BUCKET=deck
|
||||
|
||||
# MARGARET (.env en /opt/margaret/)
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=corp
|
||||
DB_USER=margaret
|
||||
DB_PASSWORD=****
|
||||
|
||||
R2_BUCKET=corp
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```yaml
|
||||
# CLARA
|
||||
version: '3.8'
|
||||
services:
|
||||
clara:
|
||||
container_name: clara-clara
|
||||
image: tzzr/clara:latest
|
||||
ports:
|
||||
- "5051:5051"
|
||||
env_file:
|
||||
- .env
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diferencias CLARA vs MARGARET
|
||||
|
||||
| Aspecto | CLARA | MARGARET |
|
||||
|---------|-------|----------|
|
||||
| Uso | Personal | Empresarial |
|
||||
| Volumen | Bajo | Alto |
|
||||
| Privacidad | Máxima | Compartida (empresa) |
|
||||
| Integración | ALFRED | JARED → MASON → FELDMAN |
|
||||
| Backup | deck bucket | corp bucket |
|
||||
|
||||
---
|
||||
|
||||
## Seguridad
|
||||
|
||||
### Actual
|
||||
- Autenticación por h_instancia
|
||||
- Comunicación HTTP (sin TLS interno)
|
||||
- .env con permisos 644 (**CRÍTICO: cambiar a 600**)
|
||||
|
||||
### Recomendado
|
||||
- TLS interno con certificados
|
||||
- Rate limiting
|
||||
- Validación de tipos MIME
|
||||
- Escaneo antivirus (ClamAV)
|
||||
|
||||
---
|
||||
|
||||
## Monitoreo
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
# CLARA
|
||||
docker logs clara-clara -f
|
||||
|
||||
# MARGARET
|
||||
docker logs margaret-margaret -f
|
||||
```
|
||||
|
||||
### Métricas Sugeridas
|
||||
- Ingestas por minuto
|
||||
- Tamaño promedio de archivos
|
||||
- Tiempo de procesamiento
|
||||
- Errores por tipo
|
||||
Reference in New Issue
Block a user