tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(v5): Complete TZZR System Documentation #1

Open
admin wants to merge 1 commits from system-v5 into main
pull from: system-v5
merge into: tzzr:main
Conversation 0 Commits 1 Files Changed 16 +4164 -2
16 changed files with 4164 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 6d15abcb1a - Show all commits

105
00_VISION/filosofia.md Normal file
View File

@@ -0,0 +1,105 @@
# Filosofía del Sistema TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## 10 Principios Fundacionales
### 1. Constructores, no gestores
Las instancias Claude son **constructores de arquitecturas**, no gestores permanentes.
- Cada instancia diseña y construye la arquitectura de un servidor
- Cuando la arquitectura esté madura, el servidor será **clonable e independiente**
- Funcionará sin necesidad de su instancia Claude
- Solo los servidores del propietario original mantienen conexión con Claude
### 2. Descentralización operativa
```
Architect App (centralizado) → Diseña moldes
↓
Instancias reales (descentralizadas)
↓
Cada una con su CORP, su DECK, sus agentes
```
### 3. Referencias ligeras mediante hashes
```
DEFINICIÓN ORIGINAL → SHA-256 → HASH UNÍVOCO (64 chars)
```
El hash es una referencia ligera que arrastra toda la información del original sin duplicarla.
### 4. Separación de planos
| Plano | Nombre | Función |
|-------|--------|---------|
| **T-N → T0** | ITM (Ítems) | Lo ideal, la partitura |
| **Burocrático** | MST (Milestones) | Documentos, hitos, estados |
| **Físico** | BCK (Bloques) | Acciones, evidencias, trabajo real |
### 5. Período flotante antes de inmutabilidad
Los datos pasan por un período flotante que permite mejora antes del sellado definitivo.
```
Dato nuevo → Período flotante (24h) → Verificación SENTINEL → Sellado FELDMAN → Inmutable
```
### 6. Renombrabilidad de agentes
Los componentes marcados como renombrables pueden personalizarse:
```
CLARA → "Lucía"
ALFRED → "Pepe"
PENNY → "Asistente"
```
Esto permite que cada usuario sienta el sistema como propio.
### 7. GRACE nunca modifica
GRACE extrae y comprende, pero **nunca modifica** el contenido original.
> "Solo extrae y comprende, nunca modifica el contenido original."
### 8. Auditoría dual: confía pero verifica
SENTINEL opera en dos modos:
| Modo | Frecuencia | Alcance | Tecnología |
|------|------------|---------|------------|
| **LIGHT** | Cada 5 min | Todos los registros | Reglas automáticas |
| **DEEP** | Cada 1 hora | Muestreo | LLM análisis |
### 9. Zero-retention en interfaces móviles
PACKET no almacena datos localmente. Todo va directo al servidor.
### 10. Curación humana en Vision Builder
```
VALORES → OBJETIVOS → IMÁGENES IA → CURACIÓN HUMANA → LO QUE SOBREVIVE DEFINE QUIÉN ERES
```
---
## Modelo de Instancias
**DECK** y **CORP** son plantillas. En producción habrá múltiples instancias:
| Tipo | Ejemplos |
|------|----------|
| **DECK** | "Deck de Juan", "Deck de Victoria", "Deck de Pablo" |
| **CORP** | "Lacitos de Colores SL", "TZR Tech", "Acme Corp" |
Cada instancia:
- Tiene su propio bucket de almacenamiento
- Puede renombrar sus agentes
- Opera de forma descentralizada
- Se conecta a servicios compartidos (GRACE, THE FACTORY, CIRCLE)

129
00_VISION/glosario.md Normal file
View File

@@ -0,0 +1,129 @@
# Glosario TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Entidades Base
| Término | Hash | Descripción | Estado |
|---------|------|-------------|--------|
| **HST** | h_maestro | Hash Semantic Tagging - Etiquetas semánticas visuales | Implementado |
| **ITM** | h_item | Ítems ideales - Definiciones del plano T0 | Planificado |
| **PLY** | h_player | Players - Identidad de actores | Planificado |
| **LOC** | h_loc | Locations - Ubicaciones geográficas | Planificado |
| **FLG** | h_flag | Flags - Marcos jurídicos y banderas | Planificado |
---
## Planos de Datos
| Plano | Tabla | Descripción |
|-------|-------|-------------|
| **T0** | items | Lo ideal, la partitura, estado futuro deseado |
| **MST** | milestones | Plano burocrático - documentos, hitos, estados |
| **BCK** | bloques | Plano físico - acciones, evidencias, trabajo real |
---
## Agentes
### Ingesta
| Agente | Servidor | Puerto | Descripción |
|--------|----------|--------|-------------|
| **CLARA** | DECK | 5051 | Recoge información personal, log inmutable |
| **MARGARET** | CORP | 5051 | Recoge información corporativa, log inmutable |
### Orquestación
| Agente | Servidor | Puerto | Descripción |
|--------|----------|--------|-------------|
| **ALFRED** | DECK | 5052 | Flujos predefinidos personales |
| **JARED** | CORP | 5052 | Flujos predefinidos corporativos (más potente) |
### Procesamiento
| Agente | Servidor | Puerto | Descripción |
|--------|----------|--------|-------------|
| **MASON** | CORP | 5053 | Enriquecimiento, ventana flotante 24h |
| **FELDMAN** | CORP | 5054 | Consolidación final, blockchain, inmutable |
| **SENTINEL** | - | - | Auditoría LIGHT (5min) + DEEP (1h) [planificado] |
---
## Servicios GPU (RunPod)
| Servicio | Endpoint | Descripción | Estado |
|----------|----------|-------------|--------|
| **GRACE** | r00x4g3rrwkbyh | IA cognitiva, extracción (18 módulos) | Bloqueado |
| **PENNY** | 0mxhaokgsmgee3 | Asistente personal, generación texto | Planificado |
| **FACTORY** | ddnuk6y35zi56a | Generación iterativa | Planificado |
---
## Servidores
| Servidor | IP | Rol |
|----------|-----|-----|
| **ARCHITECT** | 69.62.126.110 | Coordinador central, Gitea, PostgreSQL |
| **DECK** | 72.62.1.113 | Servidor personal |
| **CORP** | 92.112.181.188 | Servidor empresarial |
| **HST** | 72.62.2.84 | API tags semánticos |
| **LOCKER** | Cloudflare R2 | Almacenamiento (5 buckets) |
---
## Hashes y Identificadores
| Prefijo | Tipo | Ejemplo | Descripción |
|---------|------|---------|-------------|
| **h_maestro** | SHA-256 | `a1b2c3...` | Hash de tag HST |
| **h_instancia** | SHA-256 | `d4e5f6...` | Identidad servidor/contexto |
| **h_entrada** | SHA-256 | `g7h8i9...` | Hash contenedor ingesta |
| **h_bloque** | SHA-256 | `j0k1l2...` | Hash de bloque BCK |
| **h_milestone** | SHA-256 | `m3n4o5...` | Hash de milestone MST |
| **H_proyecto** | Prefijo | `H_tzzr_genesis` | Identificador proyecto legible |
---
## Interfaces
| Interfaz | Tipo | Descripción |
|----------|------|-------------|
| **PACKET** | App móvil | Captura multimedia, zero-retention |
| **Vision Builder** | Web | Diseño de vida mediante curación visual |
| **Mind Link** | Web | Compartición de información |
---
## Protocolos
| Protocolo | Versión | Descripción |
|-----------|---------|-------------|
| **S-CONTRACT** | v2.1 | Comunicación con IAs (context, deployment, envelope, payload) |
| **locker://** | - | Referencias almacenamiento R2 |
---
## Grupos HST
| Grupo | Cantidad | Descripción |
|-------|----------|-------------|
| **hst** | 639 | Tags del sistema base |
| **spe** | 145 | Tags específicos |
| **vsn** | 84 | Visiones |
| **flg** | 65 | Banderas/países |
| **vue** | 21 | Vistas |
| **hsu** | - | Tags usuario (extensión) |
---
## Estados de Pipeline
| Estado | Etapa | Descripción |
|--------|-------|-------------|
| **recibido** | CLARA/MARGARET | Contenedor ingresado, inmutable |
| **en_edicion** | MASON | Usuario enriqueciendo datos |
| **listo** | MASON | Listo para consolidar |
| **pendiente** | FELDMAN | En cola de consolidación |
| **consolidado** | FELDMAN | Registrado en milestone/bloque |
| **sellado** | NOTARIO | Blockchain confirmado |

154
01_ARQUITECTURA/overview.md Normal file
View File

@@ -0,0 +1,154 @@
# Arquitectura Overview
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Diagrama General
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA DE COORDINACIÓN │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ARCHITECT (69.62.126.110) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐ │ │
│ │ │PostgreSQL│ │ Gitea │ │Orchestrator│ │ Infisical │ │ │
│ │ │ central │ │ 25 repos │ │ v5 │ │ Secrets │ │ │
│ │ └──────────┘ └──────────┘ └────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA DE SERVIDORES │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │
│ │ DECK │ │ CORP │ │ HST │ │
│ │ 72.62.1.113 │ │ 92.112.181.188 │ │ 72.62.2.84 │ │
│ │ │ │ │ │ │ │
│ │ CLARA :5051 │ │ MARGARET :5051 │ │ 973 tags │ │
│ │ ALFRED :5052 │ │ JARED :5052 │ │ API pública │ │
│ │ │ │ MASON :5053 │ │ Directus :8055 │ │
│ │ Mailcow │ │ FELDMAN :5054 │ │ │ │
│ │ Vaultwarden │ │ │ │ │ │
│ │ Directus │ │ Odoo │ │ │ │
│ └───────────────────┘ │ Nextcloud │ └───────────────────┘ │
│ │ └───────────────────┘ │ │
│ │ │ │ │
│ └─────────────────────────┼──────────────────────┘ │
│ │ │
└───────────────────────────────────┼─────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA DE ALMACENAMIENTO │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Cloudflare R2 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │
│ │ │architect │ │ deck │ │ corp │ │ hst │ │ locker │ │ │
│ │ │ backups │ │ archivos │ │ archivos │ │ imágenes │ │ general│ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA GPU (RunPod) │
│ Estado: BLOQUEADO - Workers no inician │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ GRACE │ │ PENNY │ │ FACTORY │ │
│ │ 18 módulos│ │ texto │ │generación│ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## Flujo de Datos
```
PACKET (App móvil)
│
│ POST /ingest
│ Content-Type: multipart/form-data
│ X-Auth-Key: {h_instancia}
│
▼
┌─────────────────────────────────────────┐
│ CLARA (DECK) / MARGARET (CORP) │
│ │
│ 1. Validar h_instancia │
│ 2. Calcular h_entrada (SHA-256) │
│ 3. Subir archivos a R2 │
│ 4. Insertar en clara_log/margaret_log │
│ 5. Estado: 'recibido' (inmutable) │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ ALFRED (DECK) / JARED (CORP) │
│ │
│ 1. Aplicar flujos predefinidos │
│ 2. Ejecutar reglas automáticas │
│ 3. Enviar a MASON si requiere mejora │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ MASON │
│ │
│ 1. Recibir de ALFRED/JARED │
│ 2. Ventana flotante 24h │
│ 3. Usuario enriquece datos │
│ 4. [Futuro] GRACE extrae información │
│ 5. Enviar a FELDMAN cuando listo │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ FELDMAN │
│ │
│ 1. Recibir en feldman_cola │
│ 2. Validar reglas (M-001, M-002, M-003)│
│ 3. Crear milestone o bloque │
│ 4. Calcular hash_contenido │
│ 5. Encadenar (hash_previo) │
│ 6. [Futuro] Merkle tree, blockchain │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ SENTINEL (planificado) │
│ │
│ LIGHT: Cada 5 min, reglas automáticas │
│ DEEP: Cada 1 hora, muestreo con LLM │
└─────────────────────────────────────────┘
```
---
## Comunicación Entre Servidores
| Origen | Destino | Protocolo | Puerto | Propósito |
|--------|---------|-----------|--------|-----------|
| DECK | ARCHITECT | SSH/Git | 2222 | Push repos |
| DECK | R2 | HTTPS | 443 | Almacenamiento |
| CORP | ARCHITECT | SSH/Git | 2222 | Push repos |
| CORP | R2 | HTTPS | 443 | Almacenamiento |
| HST | ARCHITECT | SSH | 22 | Administración |
| ARCHITECT | DECK | SSH | 22 | Deploy |
| ARCHITECT | CORP | SSH | 22 | Deploy |
---
## Bases de Datos
| Servidor | Database | Tablas Principales |
|----------|----------|--------------------|
| ARCHITECT | architect | context_blocks, agents, creds_* |
| DECK | tzzr | clara_log, alfred_executions |
| CORP | corp | margaret_log, mason_workspace, feldman_* |
| HST | hst_images | hst_tags, hst_trees |

230
01_ARQUITECTURA/servidores.md Normal file
View File

@@ -0,0 +1,230 @@
# Servidores TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## ARCHITECT (69.62.126.110)
**Rol:** Coordinador central del sistema
### Servicios
| Servicio | Puerto | Estado |
|----------|--------|--------|
| PostgreSQL | 5432 | Operativo |
| Gitea | 3000 (HTTP), 2222 (SSH) | Operativo |
| Orchestrator App | 5050 | Operativo |
| Infisical | 8082 | Operativo |
### PostgreSQL (database: architect)
| Tabla | Descripción |
|-------|-------------|
| context_blocks | 30 bloques de contexto atómicos |
| agent_context_index | Asignaciones agente-bloque |
| agents | 6 agentes definidos |
| creds_* | 6 tablas de credenciales |
| s_contract_contexts | Contextos IA |
| s_contract_datasets | Datasets IA |
### Acceso
```bash
# SSH
ssh orchestrator@69.62.126.110
# PostgreSQL
sudo -u postgres psql -d architect
# Gitea
http://localhost:3000
```
---
## DECK (72.62.1.113)
**Rol:** Servidor personal
### Servicios
| Servicio | Puerto | Estado |
|----------|--------|--------|
| CLARA | 5051 | Operativo |
| ALFRED | 5052 | Operativo |
| Mailcow (15 containers) | SMTP, IMAP | Operativo |
| Directus | 8055 | Operativo |
| FileBrowser | 8082 | Operativo |
| Shlink | 8083 | Operativo |
| Vaultwarden | 8085 | Operativo |
| ntfy | 8080 | Operativo |
### PostgreSQL (database: tzzr)
| Tabla | Descripción |
|-------|-------------|
| clara_log | Log inmutable de ingesta |
| deck_visiones | Visiones personales |
| deck_milestones | Milestones personales |
| deck_acciones | Acciones |
| deck_habitos | Hábitos |
| deck_bck | Bloques |
### Docker Containers
```
mailcowdockerized-acme-mailcow-1
mailcowdockerized-clamd-mailcow-1
mailcowdockerized-dovecot-mailcow-1
mailcowdockerized-mysql-mailcow-1
mailcowdockerized-netfilter-mailcow-1
mailcowdockerized-nginx-mailcow-1
mailcowdockerized-olefy-mailcow-1
mailcowdockerized-php-fpm-mailcow-1
mailcowdockerized-postfix-mailcow-1
mailcowdockerized-redis-mailcow-1
mailcowdockerized-rspamd-mailcow-1
mailcowdockerized-sogo-mailcow-1
mailcowdockerized-solr-mailcow-1
mailcowdockerized-unbound-mailcow-1
mailcowdockerized-watchdog-mailcow-1
clara-clara
alfred-alfred
directus
filebrowser
shlink
vaultwarden
ntfy
```
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113
```
---
## CORP (92.112.181.188)
**Rol:** Servidor empresarial
### Servicios
| Servicio | Puerto | Estado |
|----------|--------|--------|
| MARGARET | 5051 | Operativo |
| JARED | 5052 | Operativo |
| MASON | 5053 | Operativo |
| FELDMAN | 5054 | Operativo |
| PostgreSQL | 5432 | Operativo |
| Directus | 8055 | Operativo |
| Nextcloud | 8080 | Operativo |
| Vaultwarden | 8081 | Operativo |
| Odoo | 8069 | Operativo |
| Caddy | 80/443 | Operativo |
### PostgreSQL (database: corp)
| Tabla | Descripción |
|-------|-------------|
| margaret_log | Log inmutable de ingesta |
| mason_workspace | Espacio de enriquecimiento |
| feldman_cola | Cola de consolidación |
| feldman_bloques | Bloques inmutables |
| feldman_validaciones | Auditoría validaciones |
| milestones | Plano MST |
| bloques | Plano BCK |
| hst_mirror | Mirror de tags HST |
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@92.112.181.188
```
---
## HST (72.62.2.84)
**Rol:** API de tags semánticos
### Servicios
| Servicio | Puerto | Estado |
|----------|--------|--------|
| Nginx | 80/443 | Operativo |
| Directus | 8055 | Operativo |
| PostgreSQL | 5432 | Operativo |
### Estadísticas HST
| Grupo | Cantidad |
|-------|----------|
| hst | 639 |
| spe | 145 |
| vsn | 84 |
| flg | 65 |
| vue | 21 |
| **Total** | **973** |
### API
```
https://tzrtech.org/{h_maestro}.png # Imagen de tag
```
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@72.62.2.84
```
---
## LOCKER (Cloudflare R2)
**Rol:** Almacenamiento distribuido
### Endpoint
```
https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```
### Buckets
| Bucket | Uso |
|--------|-----|
| architect | Backups Gitea, configs, GPU services |
| deck | Archivos personales (CLARA) |
| corp | Archivos empresariales (MARGARET) |
| hst | Imágenes de tags |
| locker | Almacenamiento general/temporal |
### Estructura GPU Services
```
s3://architect/gpu-services/
├── base/
│ └── bootstrap.sh
├── grace/
│ └── code/handler.py
├── penny/
│ └── code/handler.py
└── factory/
└── code/handler.py
```
---
## Resumen de IPs
| Servidor | IP Pública | IP Interna |
|----------|------------|------------|
| ARCHITECT | 69.62.126.110 | localhost |
| DECK | 72.62.1.113 | - |
| CORP | 92.112.181.188 | - |
| HST | 72.62.2.84 | - |

237
02_MODELO_DATOS/entidades.md Normal file
View File

@@ -0,0 +1,237 @@
# Entidades Base TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Visión General
Las entidades base son los bloques fundamentales del sistema. Cada una tiene un hash único SHA-256 que la identifica de forma unívoca.
```
DEFINICIÓN ORIGINAL → SHA-256 → h_{tipo} (64 chars)
```
---
## HST (Hash Semantic Tagging)
**Estado:** Implementado
**Servidor:** HST (72.62.2.84)
**Hash:** h_maestro
### Fórmula
```
h_maestro = SHA-256(grupo:ref)
```
### Grupos
| Grupo | Cantidad | Descripción |
|-------|----------|-------------|
| hst | 639 | Tags del sistema base |
| spe | 145 | Tags específicos |
| vsn | 84 | Visiones |
| flg | 65 | Banderas/países |
| vue | 21 | Vistas |
### Schema
```sql
CREATE TABLE hst_tags (
id SERIAL PRIMARY KEY,
ref VARCHAR(100) UNIQUE NOT NULL,
h_maestro VARCHAR(64) UNIQUE NOT NULL,
grupo VARCHAR(50) NOT NULL,
nombre_es VARCHAR(255),
nombre_en VARCHAR(255),
descripcion TEXT,
imagen_url TEXT,
activo BOOLEAN DEFAULT true,
version INTEGER DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW()
);
```
### Ejemplo
```json
{
"ref": "person",
"h_maestro": "a1b2c3d4e5f6...",
"grupo": "hst",
"nombre_es": "Persona",
"nombre_en": "Person",
"imagen_url": "https://tzrtech.org/a1b2c3d4e5f6...png"
}
```
---
## ITM (Items - Plano Ideal)
**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_item
### Concepto
Los ITM representan el estado ideal futuro. Son la "partitura" que guía las acciones.
### Schema Propuesto
```sql
CREATE TABLE items (
id BIGSERIAL PRIMARY KEY,
h_item VARCHAR(64) UNIQUE NOT NULL,
h_instancia VARCHAR(64) NOT NULL,
secuencia BIGINT NOT NULL,
hash_previo VARCHAR(64),
hash_contenido VARCHAR(64),
tipo_item VARCHAR(50) NOT NULL, -- accion_ideal, objetivo, requerimiento
titulo VARCHAR(255) NOT NULL,
descripcion TEXT,
criterios_aceptacion JSONB,
metadata JSONB,
proyecto_tag VARCHAR(64),
etiquetas JSONB,
estado VARCHAR(20) DEFAULT 'draft', -- draft, vigente, obsoleto
created_at TIMESTAMPTZ DEFAULT NOW(),
created_by VARCHAR(64),
UNIQUE (h_instancia, secuencia)
);
```
---
## PLY (Players - Identidad)
**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_player
### Concepto
Los PLY representan la identidad de actores en el sistema (personas, empresas, agentes).
### Schema Propuesto
```sql
CREATE TABLE players (
id BIGSERIAL PRIMARY KEY,
h_player VARCHAR(64) UNIQUE NOT NULL,
tipo VARCHAR(50) NOT NULL, -- persona, empresa, agente
nombre VARCHAR(255) NOT NULL,
email VARCHAR(255),
metadata JSONB,
activo BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## LOC (Locations - Ubicaciones)
**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_loc
### Concepto
Los LOC representan ubicaciones geográficas con precisión variable.
### Schema Propuesto
```sql
CREATE TABLE locations (
id BIGSERIAL PRIMARY KEY,
h_loc VARCHAR(64) UNIQUE NOT NULL,
nombre VARCHAR(255),
lat DECIMAL(10, 8),
lon DECIMAL(11, 8),
precision_metros INTEGER,
tipo VARCHAR(50), -- punto, area, ruta
metadata JSONB,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
### Fórmula Hash
```
h_loc = SHA-256(lat:lon:precision)
```
---
## FLG (Flags - Marcos Jurídicos)
**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_flag
### Concepto
Los FLG representan marcos jurídicos, normativas, países.
### Notas
Actualmente existe un grupo `flg` en HST con 65 tags de países, pero no como entidad independiente.
---
## Tags de Usuario (Extensiones)
Los usuarios pueden crear sus propios tags como extensiones de HST.
| Tabla | Descripción |
|-------|-------------|
| hsu | HST Usuario |
| spu | SPE Usuario |
| vsu | VSN Usuario |
| vuu | VUE Usuario |
| pju | Proyectos Usuario |
| flu | FLG Usuario |
### Schema
```sql
CREATE TABLE hsu (
id SERIAL PRIMARY KEY,
ref VARCHAR(10) NOT NULL,
h_usuario VARCHAR(64) NOT NULL,
nombre VARCHAR(255) NOT NULL,
user_id INTEGER REFERENCES users(id),
metadata JSONB,
activo BOOLEAN DEFAULT true,
created_at TIMESTAMP DEFAULT NOW(),
UNIQUE (user_id, ref)
);
```
---
## Relaciones Entre Entidades
```
ITM (ideal)
│
├──► h_maestro (HST tags)
├──► h_player (PLY responsable)
├──► h_loc (LOC ubicación)
└──► h_flag (FLG normativa)
MST (milestone)
│
├──► item_asociado (ITM)
└──► h_maestro (HST tags)
BCK (bloque)
│
├──► item_asociado (ITM)
├──► milestone_asociado (MST)
└──► h_maestro (HST tags)
```

309
02_MODELO_DATOS/planos.md Normal file
View File

@@ -0,0 +1,309 @@
# Planos de Datos TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Visión General
El sistema TZZR utiliza tres planos conceptuales para organizar la información:
```
┌─────────────────────────────────────────────────────────────────┐
│ T0 - PLANO IDEAL │
│ ITM (Items): Objetivos, acciones ideales, requerimientos │
│ Estado: PLANIFICADO - Sin implementación actual │
└─────────────────────────────────────────────────────────────────┘
│
▼ materializa
┌─────────────────────────────────────────────────────────────────┐
│ MST - MILESTONES │
│ Compromisos futuros con fecha de vencimiento │
│ Estado: IMPLEMENTADO en CORP (tabla milestones) │
└─────────────────────────────────────────────────────────────────┘
│
▼ cumple/genera
┌─────────────────────────────────────────────────────────────────┐
│ BCK - BLOQUES │
│ Hechos inmutables del pasado (blockchain-ready) │
│ Estado: IMPLEMENTADO en CORP (tabla bloques) │
└─────────────────────────────────────────────────────────────────┘
```
---
## T0 - Plano Ideal (ITM)
### Concepto
El plano T0 contiene los Items (ITM) que representan el estado ideal futuro. Son la "partitura" que guía las acciones.
### Tipos de Items
| Tipo | Descripción |
|------|-------------|
| accion_ideal | Acción que debería ejecutarse |
| objetivo | Meta a alcanzar |
| requerimiento | Requisito a cumplir |
### Estado de Implementación
**PLANIFICADO** - Schema definido pero sin tablas creadas.
### Schema Propuesto
```sql
CREATE TABLE items (
id BIGSERIAL PRIMARY KEY,
h_item VARCHAR(64) UNIQUE NOT NULL,
h_instancia VARCHAR(64) NOT NULL,
secuencia BIGINT NOT NULL,
hash_previo VARCHAR(64),
hash_contenido VARCHAR(64),
tipo_item VARCHAR(50) NOT NULL,
titulo VARCHAR(255) NOT NULL,
descripcion TEXT,
criterios_aceptacion JSONB,
metadata JSONB,
proyecto_tag VARCHAR(64),
etiquetas JSONB,
estado VARCHAR(20) DEFAULT 'draft',
created_at TIMESTAMPTZ DEFAULT NOW(),
created_by VARCHAR(64),
UNIQUE (h_instancia, secuencia)
);
```
---
## MST - Milestones
### Concepto
Los milestones representan compromisos con fecha futura. Tienen un período flotante de 24 horas antes de consolidarse.
### Estado de Implementación
**IMPLEMENTADO** en CORP (database: corp).
### Schema Actual
```sql
-- Tabla: milestones (CORP)
CREATE TABLE milestones (
id BIGSERIAL PRIMARY KEY,
h_milestone VARCHAR(64) UNIQUE NOT NULL,
h_instancia VARCHAR(64) NOT NULL,
secuencia BIGINT NOT NULL,
hash_previo VARCHAR(64),
hash_contenido VARCHAR(64),
tipo_milestone VARCHAR(50) NOT NULL,
fecha_vencimiento DATE NOT NULL,
descripcion TEXT,
metadata JSONB,
proyecto_tag VARCHAR(64),
etiquetas JSONB,
estado VARCHAR(20) DEFAULT 'draft',
created_at TIMESTAMPTZ DEFAULT NOW(),
modified_at TIMESTAMPTZ,
created_by VARCHAR(64),
UNIQUE (h_instancia, secuencia)
);
```
### Tipos de Milestones
| Tipo | Descripción |
|------|-------------|
| compromiso | Compromiso de entrega |
| deadline | Fecha límite |
| evento | Evento programado |
| recordatorio | Recordatorio futuro |
### Fórmula Hash
```
h_milestone = SHA-256(h_instancia:secuencia:tipo:contenido)
```
### Período Flotante
- **Duración:** 24 horas desde creación
- **Durante período:** Modificable vía MASON
- **Después:** Inmutable, solo lectura
**Nota:** Actualmente no hay scheduler que procese la expiración automáticamente.
---
## BCK - Bloques
### Concepto
Los bloques son registros inmutables de hechos pasados. Cada bloque está encadenado al anterior mediante hash, preparando la infraestructura para blockchain.
### Estado de Implementación
**IMPLEMENTADO** en CORP (database: corp).
### Schema Actual
```sql
-- Tabla: bloques (CORP)
CREATE TABLE bloques (
id BIGSERIAL PRIMARY KEY,
h_bloque VARCHAR(64) UNIQUE NOT NULL,
h_instancia VARCHAR(64) NOT NULL,
secuencia BIGINT NOT NULL,
hash_previo VARCHAR(64),
hash_contenido VARCHAR(64) NOT NULL,
tipo_bloque VARCHAR(50) NOT NULL,
contenido JSONB NOT NULL,
metadata JSONB,
item_asociado VARCHAR(64),
milestone_asociado VARCHAR(64),
h_maestro JSONB,
h_player VARCHAR(64),
h_loc VARCHAR(64),
h_flag VARCHAR(64),
estado VARCHAR(20) DEFAULT 'consolidado',
created_at TIMESTAMPTZ DEFAULT NOW(),
validated_at TIMESTAMPTZ,
validated_by VARCHAR(64),
UNIQUE (h_instancia, secuencia)
);
```
### Tipos de Bloques
| Tipo | Descripción |
|------|-------------|
| transaccion | Transacción económica |
| documento | Documento consolidado |
| evento | Evento registrado |
| milestone_cumplido | Milestone que se cumplió |
### Fórmula Hash
```
h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido)
hash_contenido = SHA-256(contenido_serializado)
```
### Encadenamiento
```
Bloque N-1 Bloque N
┌──────────────────┐ ┌──────────────────┐
│ h_bloque: abc123 │ ──────► │ hash_previo: │
│ hash_contenido: │ │ abc123 │
│ def456 │ │ h_bloque: ghi789 │
│ secuencia: 1 │ │ secuencia: 2 │
└──────────────────┘ └──────────────────┘
```
---
## Flujo Entre Planos
```
Usuario crea ITM
│
▼
ITM (T0) "Objetivo: Completar proyecto X"
│
│ materializa
▼
MST "Milestone: Entrega módulo 1 - 2024-01-15"
│
│ [período flotante 24h]
│
▼
MASON (enriquecimiento)
│
▼
FELDMAN (validación)
│
│ cumple/genera
▼
BCK "Bloque: Módulo 1 entregado - 2024-01-14"
│
▼
Inmutable ✓
```
---
## Tablas de Procesamiento
### FELDMAN Cola
```sql
-- feldman_cola: Elementos pendientes de validación
CREATE TABLE feldman_cola (
id BIGSERIAL PRIMARY KEY,
tipo VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque'
h_entrada VARCHAR(64) NOT NULL,
contenido JSONB NOT NULL,
prioridad INTEGER DEFAULT 0,
estado VARCHAR(20) DEFAULT 'pendiente',
created_at TIMESTAMPTZ DEFAULT NOW(),
processed_at TIMESTAMPTZ
);
```
### FELDMAN Validaciones
```sql
-- feldman_validaciones: Auditoría de validaciones
CREATE TABLE feldman_validaciones (
id BIGSERIAL PRIMARY KEY,
h_entrada VARCHAR(64) NOT NULL,
regla VARCHAR(50) NOT NULL, -- M-001, M-002, M-003
resultado BOOLEAN NOT NULL,
mensaje TEXT,
validated_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## Reglas de Validación FELDMAN
| Regla | Nombre | Descripción |
|-------|--------|-------------|
| M-001 | Hash único | h_bloque/h_milestone no existe previamente |
| M-002 | Encadenamiento | hash_previo apunta a bloque existente |
| M-003 | Integridad | hash_contenido = SHA-256(contenido) |
---
## Decisiones de Diseño
### D-004: Eliminar columnas duplicadas
**Problema:** Milestones tienen columnas + JSONB duplicados.
**Decisión:** Mantener metadatos solo en JSONB `metadata`.
### D-007: Timestamps UTC
**Problema:** Inconsistencia en zonas horarias.
**Decisión:** Usar `TIMESTAMPTZ` y almacenar en UTC.
---
## Roadmap
### Implementado
- [x] Tabla milestones en CORP
- [x] Tabla bloques en CORP
- [x] Fórmulas hash definidas
### Pendiente
- [ ] Tabla items (T0)
- [ ] Scheduler para período flotante
- [ ] Merkle tree para verificación
- [ ] Smart contract blockchain (futuro)

311
03_COMPONENTES/agentes/clara-margaret.md Normal file
View 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

390
03_COMPONENTES/agentes/feldman.md Normal file
View File

@@ -0,0 +1,390 @@
# FELDMAN - Agente de Consolidación
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Resumen
| Aspecto | Valor |
|---------|-------|
| Servidor | CORP (92.112.181.188) |
| Puerto | 5054 |
| Base de datos | corp |
| Tablas | feldman_cola, feldman_bloques, feldman_validaciones |
| Estado | Operativo |
---
## Rol en el Sistema
FELDMAN es el "notario" del sistema: valida y consolida datos en bloques inmutables.
```
MASON (enriquecido)
│
▼
┌─────────────────────────────────────────┐
│ FELDMAN │
│ │
│ 1. Recibir en feldman_cola │
│ 2. Validar reglas (M-001, M-002, M-003)│
│ 3. Calcular hash_contenido │
│ 4. Encadenar (hash_previo) │
│ 5. Crear milestone o bloque │
│ 6. Marcar como consolidado │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ milestones / bloques (inmutables) │
└─────────────────────────────────────────┘
│
▼
SENTINEL (auditoría futura)
```
---
## Reglas de Validación
| Regla | Nombre | Descripción | Acción si falla |
|-------|--------|-------------|-----------------|
| M-001 | Hash único | h_bloque/h_milestone no existe previamente | Rechazar |
| M-002 | Encadenamiento | hash_previo apunta a bloque existente | Rechazar |
| M-003 | Integridad | hash_contenido = SHA-256(contenido) | Rechazar |
### Implementación
```python
def validar_m001(h_bloque):
"""M-001: Hash debe ser único."""
existe = db.execute(
"SELECT 1 FROM bloques WHERE h_bloque = %s",
[h_bloque]
).fetchone()
return existe is None
def validar_m002(hash_previo, h_instancia):
"""M-002: hash_previo debe existir (excepto génesis)."""
if hash_previo is None:
# Primer bloque de la instancia (génesis)
existe = db.execute(
"SELECT 1 FROM bloques WHERE h_instancia = %s",
[h_instancia]
).fetchone()
return existe is None # OK si no hay bloques previos
existe = db.execute(
"SELECT 1 FROM bloques WHERE h_bloque = %s",
[hash_previo]
).fetchone()
return existe is not None
def validar_m003(hash_contenido, contenido):
"""M-003: Hash debe coincidir con contenido."""
import hashlib
import json
contenido_serializado = json.dumps(contenido, sort_keys=True)
hash_calculado = hashlib.sha256(contenido_serializado.encode()).hexdigest()
return hash_contenido == hash_calculado
```
---
## Schema de Tablas
### feldman_cola
```sql
CREATE TABLE feldman_cola (
id BIGSERIAL PRIMARY KEY,
tipo VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque'
h_entrada VARCHAR(64) NOT NULL, -- Referencia a origen
h_instancia VARCHAR(64) NOT NULL,
contenido JSONB NOT NULL,
prioridad INTEGER DEFAULT 0,
estado VARCHAR(20) DEFAULT 'pendiente',
intentos INTEGER DEFAULT 0,
ultimo_error TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
processed_at TIMESTAMPTZ
);
CREATE INDEX idx_feldman_cola_estado ON feldman_cola(estado);
CREATE INDEX idx_feldman_cola_prioridad ON feldman_cola(prioridad DESC);
```
### feldman_bloques (alias de bloques)
```sql
-- Ver 02_MODELO_DATOS/planos.md para schema completo
CREATE TABLE bloques (
id BIGSERIAL PRIMARY KEY,
h_bloque VARCHAR(64) UNIQUE NOT NULL,
h_instancia VARCHAR(64) NOT NULL,
secuencia BIGINT NOT NULL,
hash_previo VARCHAR(64),
hash_contenido VARCHAR(64) NOT NULL,
tipo_bloque VARCHAR(50) NOT NULL,
contenido JSONB NOT NULL,
-- ... campos adicionales
UNIQUE (h_instancia, secuencia)
);
```
### feldman_validaciones
```sql
CREATE TABLE feldman_validaciones (
id BIGSERIAL PRIMARY KEY,
h_entrada VARCHAR(64) NOT NULL,
tipo_destino VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque'
h_destino VARCHAR(64), -- h_milestone o h_bloque
regla VARCHAR(50) NOT NULL, -- M-001, M-002, M-003
resultado BOOLEAN NOT NULL,
mensaje TEXT,
validated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_feldman_val_entrada ON feldman_validaciones(h_entrada);
```
---
## Flujo de Consolidación
```
1. Entrada en feldman_cola
│
▼
2. FELDMAN procesa (poll cada N segundos)
│
├─► Validar M-001 (hash único)
│ ├─ PASS → continuar
│ └─ FAIL → registrar error, marcar 'rechazado'
│
├─► Validar M-002 (encadenamiento)
│ ├─ PASS → continuar
│ └─ FAIL → registrar error, marcar 'rechazado'
│
├─► Validar M-003 (integridad)
│ ├─ PASS → continuar
│ └─ FAIL → registrar error, marcar 'rechazado'
│
▼
3. Todas las validaciones PASS
│
▼
4. Obtener última secuencia de h_instancia
│
▼
5. Calcular h_bloque/h_milestone
│
▼
6. INSERT en bloques/milestones
│
▼
7. Actualizar feldman_cola → 'consolidado'
│
▼
8. Registrar en feldman_validaciones
```
---
## Cálculo de Hashes
### h_bloque
```python
def calcular_h_bloque(h_instancia, secuencia, hash_previo, hash_contenido):
"""
Calcula el hash del bloque.
h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido)
"""
import hashlib
# hash_previo puede ser None para bloque génesis
previo = hash_previo or "genesis"
data = f"{h_instancia}:{secuencia}:{previo}:{hash_contenido}"
return hashlib.sha256(data.encode()).hexdigest()
```
### hash_contenido
```python
def calcular_hash_contenido(contenido):
"""
Calcula el hash del contenido.
hash_contenido = SHA-256(contenido_serializado)
"""
import hashlib
import json
# Serialización determinista
contenido_str = json.dumps(contenido, sort_keys=True, ensure_ascii=False)
return hashlib.sha256(contenido_str.encode()).hexdigest()
```
---
## API Endpoints
### POST /consolidar
```http
POST /consolidar HTTP/1.1
Host: corp.example.com:5054
Content-Type: application/json
```
### Response (éxito)
```json
{
"success": true,
"h_bloque": "ghi789...",
"secuencia": 42,
"hash_contenido": "jkl012...",
"validaciones": {
"M-001": true,
"M-002": true,
"M-003": true
}
}
```
### Response (error)
```json
{
"success": false,
"error": "Validación fallida",
"validaciones": {
"M-001": true,
"M-002": false,
"M-003": true
},
"mensaje": "M-002: hash_previo no existe en cadena"
}
```
---
## Configuración
### Variables de Entorno
```bash
# /opt/feldman/.env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=corp
DB_USER=feldman
DB_PASSWORD=****
POLL_INTERVAL=5 # Segundos entre polls
MAX_BATCH=10 # Elementos por lote
MAX_RETRIES=3 # Reintentos antes de rechazar
```
---
## Estados de la Cola
| Estado | Descripción |
|--------|-------------|
| pendiente | En espera de procesamiento |
| procesando | FELDMAN está validando |
| consolidado | Validado y creado bloque/milestone |
| rechazado | Falló validación, no se reintentará |
| error | Error técnico, puede reintentarse |
---
## Auditoría
Cada validación se registra en `feldman_validaciones`:
```sql
-- Consultar historial de validaciones
SELECT
h_entrada,
regla,
resultado,
mensaje,
validated_at
FROM feldman_validaciones
WHERE h_entrada = 'abc123...'
ORDER BY validated_at;
```
---
## Futuro: Blockchain
FELDMAN está diseñado para evolucionar hacia blockchain:
1. **Actual:** Encadenamiento por hash_previo en PostgreSQL
2. **Fase 2:** Merkle tree para verificación eficiente
3. **Fase 3:** Smart contract en blockchain (Ethereum/Polygon)
```
Merkle Root
│
┌───────────┴───────────┐
│ │
Hash(AB) Hash(CD)
│ │
┌─────┴─────┐ ┌─────┴─────┐
│ │ │ │
Hash(A) Hash(B) Hash(C) Hash(D)
│ │ │ │
Bloque A Bloque B Bloque C Bloque D
```
---
## Monitoreo
### Logs
```bash
docker logs feldman-feldman -f
```
### Consultas de Estado
```sql
-- Elementos pendientes
SELECT COUNT(*) FROM feldman_cola WHERE estado = 'pendiente';
-- Últimas validaciones fallidas
SELECT * FROM feldman_validaciones
WHERE resultado = false
ORDER BY validated_at DESC
LIMIT 10;
-- Bloques creados hoy
SELECT COUNT(*) FROM bloques
WHERE created_at >= CURRENT_DATE;
```
-- Últimas validaciones fallidas
SELECT * FROM feldman_validaciones
WHERE resultado = false
ORDER BY validated_at DESC
LIMIT 10;
-- Bloques creados hoy
SELECT COUNT(*) FROM bloques
WHERE created_at >= CURRENT_DATE;
```

403
03_COMPONENTES/servicios/grace.md Normal file
View File

@@ -0,0 +1,403 @@
# GRACE - Servicio de IA Cognitiva
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Estado Actual
**BLOQUEADO:** RunPod no inicia workers.
| Aspecto | Valor |
|---------|-------|
| Plataforma | RunPod Serverless |
| Endpoint ID | r00x4g3rrwkbyh |
| Balance | ~$72 USD |
| Workers activos | 0 |
| Estado | Inoperativo |
---
## Descripción
GRACE es el servicio de extracción de información mediante IA. Procesa contenido multimedia para extraer datos estructurados.
```
Contenido Raw
(audio, imagen, video, documento)
│
▼
┌─────────────────────────────────────────┐
│ GRACE (GPU) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ ASR │ │ OCR │ │ TTS │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Face │ │Embeddings│ │ Avatar │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ + 12 módulos pendientes │
└─────────────────────────────────────────┘
│
▼
Datos Estructurados
(JSON, vectores, metadatos)
```
---
## Módulos Implementados (6 de 18)
### ASR - Automatic Speech Recognition
| Campo | Valor |
|-------|-------|
| Modelo | Whisper Large v3 |
| Input | Audio (mp3, wav, m4a) |
| Output | Texto + timestamps |
| GPU | A10G recomendado |
```python
@grace.module("asr")
def process_asr(audio_bytes: bytes) -> dict:
"""Transcribe audio a texto."""
model = whisper.load_model("large-v3")
result = model.transcribe(audio_bytes)
return {
"text": result["text"],
"segments": result["segments"],
"language": result["language"]
}
```
### OCR - Optical Character Recognition
| Campo | Valor |
|-------|-------|
| Modelo | EasyOCR + Tesseract |
| Input | Imagen (jpg, png) |
| Output | Texto + bounding boxes |
| GPU | A10G recomendado |
```python
@grace.module("ocr")
def process_ocr(image_bytes: bytes) -> dict:
"""Extrae texto de imagen."""
reader = easyocr.Reader(['es', 'en'])
result = reader.readtext(image_bytes)
return {
"text": " ".join([r[1] for r in result]),
"boxes": [{"text": r[1], "bbox": r[0], "confidence": r[2]} for r in result]
}
```
### TTS - Text to Speech
| Campo | Valor |
|-------|-------|
| Modelo | Coqui TTS |
| Input | Texto |
| Output | Audio (wav) |
| GPU | A10G recomendado |
### Face - Reconocimiento Facial
| Campo | Valor |
|-------|-------|
| Modelo | InsightFace |
| Input | Imagen |
| Output | Embeddings faciales |
| GPU | A10G recomendado |
### Embeddings - Vectores Semánticos
| Campo | Valor |
|-------|-------|
| Modelo | Sentence Transformers |
| Input | Texto |
| Output | Vector 384/768 dims |
| GPU | A10G recomendado |
### Avatar - Generación de Avatares
| Campo | Valor |
|-------|-------|
| Modelo | StyleGAN |
| Input | Imagen facial |
| Output | Avatar estilizado |
| GPU | A10G recomendado |
---
## Módulos Pendientes (12)
| Módulo | Descripción | Prioridad |
|--------|-------------|-----------|
| Document parsing | Extracción de PDFs | Alta |
| Image classification | Clasificación de imágenes | Media |
| Object detection | Detección de objetos | Media |
| Sentiment analysis | Análisis de sentimiento | Media |
| Named entity recognition | Extracción de entidades | Alta |
| Translation | Traducción de texto | Media |
| Summarization | Resumen de texto | Media |
| Question answering | Respuestas a preguntas | Baja |
| Code generation | Generación de código | Baja |
| Audio classification | Clasificación de audio | Baja |
| Video analysis | Análisis de video | Baja |
| Multimodal fusion | Fusión multimodal | Baja |
---
## Código en R2
El código está listo y disponible:
```
s3://architect/gpu-services/
├── base/
│ └── bootstrap.sh # Script de inicialización
├── grace/
│ └── code/
│ └── handler.py # Handler principal
├── penny/
│ └── code/
│ └── handler.py
└── factory/
└── code/
└── handler.py
```
### Descargar Código
```bash
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
aws s3 sync s3://architect/gpu-services/grace/ ./grace/ \
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```
---
## Handler RunPod
```python
import runpod
def handler(event):
"""
Handler principal de GRACE para RunPod Serverless.
Input:
{
"input": {
"module": "asr|ocr|tts|face|embeddings|avatar",
"data": "base64 encoded content",
"options": {}
}
}
Output:
{
"output": { ... resultado del módulo ... },
"error": null
}
"""
try:
module = event["input"]["module"]
data = base64.b64decode(event["input"]["data"])
options = event["input"].get("options", {})
if module == "asr":
result = process_asr(data, **options)
elif module == "ocr":
result = process_ocr(data, **options)
elif module == "tts":
result = process_tts(data, **options)
elif module == "face":
result = process_face(data, **options)
elif module == "embeddings":
result = process_embeddings(data, **options)
elif module == "avatar":
result = process_avatar(data, **options)
else:
return {"error": f"Módulo desconocido: {module}"}
return {"output": result, "error": None}
except Exception as e:
return {"error": str(e)}
runpod.serverless.start({"handler": handler})
```
---
## Uso desde MASON
```python
import runpod
import base64
runpod.api_key = "..." # Desde Infisical
def call_grace(module: str, content: bytes, options: dict = None) -> dict:
"""Llama a GRACE para procesar contenido."""
job = runpod.run(
endpoint_id="r00x4g3rrwkbyh",
input={
"module": module,
"data": base64.b64encode(content).decode(),
"options": options or {}
}
)
# Polling hasta completar
while True:
status = runpod.status(job["id"])
if status["status"] == "COMPLETED":
return status["output"]
elif status["status"] == "FAILED":
raise Exception(status.get("error", "Job failed"))
time.sleep(1)
```
---
## Problema Actual: Workers No Inician
### Incidente 2024-12-24
- **Síntoma:** 0 workers activos a pesar de jobs en cola
- **Balance:** $72+ (suficiente)
- **Configuración:** Correcta
- **Causa probable:** Problema de capacidad RunPod
### Intentos de Diagnóstico
1. Verificado endpoint activo en dashboard
2. Verificado balance suficiente
3. Verificado configuración de scaling
4. Jobs quedan en estado "IN_QUEUE" indefinidamente
### Log de Errores
```
No hay logs disponibles - workers nunca inician
```
---
## Alternativas Evaluadas
### 1. Modal (Recomendado)
```python
import modal
stub = modal.Stub("grace")
image = modal.Image.debian_slim().pip_install("whisper", "easyocr")
@stub.function(gpu="A10G", image=image)
def process_asr(audio_bytes: bytes) -> dict:
import whisper
model = whisper.load_model("large-v3")
result = model.transcribe(audio_bytes)
return {"text": result["text"]}
```
**Pros:**
- Serverless real
- Buen DX (developer experience)
- Python-native
- Cold start rápido
**Contras:**
- Menos GPUs disponibles que RunPod
- Pricing puede ser mayor
### 2. Replicate
```python
import replicate
output = replicate.run(
"openai/whisper:large-v3",
input={"audio": audio_url}
)
```
**Pros:**
- Modelos pre-entrenados
- API simple
- Sin gestión de infraestructura
**Contras:**
- Menos control
- Más caro a escala
- Dependencia de modelos de terceros
### 3. Lambda Labs
**Pros:**
- Hardware dedicado
- GPUs disponibles
**Contras:**
- Menos flexible
- Reserva manual
- No serverless
### 4. Self-Hosted
**Pros:**
- Control total
- Sin dependencias externas
- Costo fijo a largo plazo
**Contras:**
- CapEx alto
- Mantenimiento
- Requiere expertise
---
## Plan de Migración
### Fase 1: Evaluación
- [ ] Crear cuenta Modal
- [ ] Portar módulo ASR a Modal
- [ ] Comparar latencia con RunPod (cuando funcione)
- [ ] Comparar costos
### Fase 2: Migración
- [ ] Portar 6 handlers a Modal
- [ ] Actualizar endpoints en MASON
- [ ] Actualizar documentación
- [ ] Testing end-to-end
### Fase 3: Producción
- [ ] Desplegar en Modal
- [ ] Monitorear costos y performance
- [ ] Deprecar RunPod endpoints
- [ ] Cancelar cuenta RunPod
---
## Principio Fundamental
**GRACE nunca modifica datos.**
GRACE es read-only: extrae información pero no puede modificar el contenido original ni los datos del sistema. Las extracciones se almacenan como metadatos asociados al contenido original.
```
Contenido Original ────► GRACE ────► Metadatos Extraídos
(inmutable) (nuevos datos)
```

177
04_SEGURIDAD/modelo-amenazas.md Normal file
View File

@@ -0,0 +1,177 @@
# Modelo de Amenazas TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Resumen Ejecutivo
El sistema TZZR tiene una base de seguridad sólida (SSH keys, PostgreSQL SSL, tokens de autenticación) pero presenta exposiciones críticas que requieren atención inmediata.
---
## Hallazgos Críticos
### CRÍTICO-001: CORP/HST sin Firewall
**Descripción:** UFW inactivo en servidores CORP y HST.
**Impacto:** Todos los puertos expuestos a Internet.
**Evidencia:** `ufw status` devuelve "inactive".
**Mitigación:**
```bash
# CORP
ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
# HST
ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
```
### CRÍTICO-002: PostgreSQL 5432 Expuesto
**Descripción:** PostgreSQL en ARCHITECT escucha en 0.0.0.0:5432.
**Impacto:** Accesible desde cualquier IP (aunque requiere autenticación).
**Mitigación:**
```
# /etc/postgresql/16/main/postgresql.conf
listen_addresses = '127.0.0.1,172.17.0.1'
```
### CRÍTICO-003: Archivos .env Legibles
**Descripción:** Archivos .env con permisos 644 (legibles por todos).
**Impacto:** Credenciales accesibles a cualquier usuario del sistema.
**Mitigación:**
```bash
chmod 600 /opt/clara/.env
chmod 600 /opt/alfred/.env
chmod 600 /opt/margaret/.env
chmod 600 /opt/mason/.env
```
---
## Hallazgos Altos
### ALTO-001: fail2ban No Configurado
**Descripción:** fail2ban failed en DECK, inactive en CORP.
**Impacto:** SSH bruteforce sin mitigación automática.
**Evidencia:** Ataques activos desde 165.232.81.204, 188.166.115.48.
**Mitigación:**
```bash
apt install fail2ban
systemctl enable fail2ban
# jail: sshd, maxretry=3, bantime=1h
```
### ALTO-002: Triple Gestión de Secretos
**Descripción:** Credenciales en Infisical, tablas creds_*, y archivos .env.
**Impacto:** No hay fuente única de verdad, riesgo de desincronización.
**Mitigación:**
- Migrar todas las credenciales a Infisical
- Eliminar .env hardcodeados
- creds_* solo para referencia
### ALTO-003: Servicios sin TLS Interno
**Descripción:** CLARA, MARGARET, MASON, FELDMAN en HTTP plano.
**Impacto:** Tráfico interno sin cifrar.
**Mitigación:**
- Configurar mTLS entre servicios
- Usar Caddy como reverse proxy con TLS
---
## Hallazgos Medios
### MEDIO-001: No hay Backup PostgreSQL
**Descripción:** Solo Gitea tiene backup en R2, PostgreSQL sin backup.
**Impacto:** Pérdida de datos en caso de fallo.
**Mitigación:**
```bash
# Cron diario
pg_dump architect | gzip | aws s3 cp - s3://architect/backups/architect_$(date +%F).sql.gz
```
### MEDIO-002: SENTINEL No Desplegado
**Descripción:** Sistema de auditoría planificado pero no implementado.
**Impacto:** Sin visibilidad de anomalías.
**Mitigación:** Implementar SENTINEL LIGHT mode básico.
### MEDIO-003: No hay Rotación de Secretos
**Descripción:** Sin política de rotación de credenciales.
**Impacto:** Credenciales comprometidas persisten indefinidamente.
**Mitigación:**
- API keys: 90 días
- DB passwords: 180 días
- SSH keys: 365 días
---
## Controles Existentes
| Control | Estado | Notas |
|---------|--------|-------|
| SSH Keys | Activo | Permisos 600 correctos |
| PostgreSQL SSL | Activo | SCRAM-SHA-256 |
| H_INSTANCIA Auth | Activo | CLARA/MARGARET |
| Gitea Tokens | Activo | Lectura/Escritura separados |
| DECK UFW | Activo | Política deny incoming |
---
## Matriz de Riesgos
| ID | Riesgo | Probabilidad | Impacto | Prioridad |
|----|--------|--------------|---------|-----------|
| CRÍTICO-001 | Firewall desactivado | Alta | Alto | Semana 1 |
| CRÍTICO-002 | PostgreSQL expuesto | Media | Alto | Semana 1 |
| CRÍTICO-003 | .env legibles | Alta | Alto | Semana 1 |
| ALTO-001 | Sin fail2ban | Alta | Medio | Semana 1 |
| ALTO-002 | Secretos duplicados | Media | Medio | Mes 1 |
| ALTO-003 | Sin TLS interno | Baja | Medio | Mes 1 |
| MEDIO-001 | Sin backup PG | Baja | Alto | Mes 1 |
| MEDIO-002 | Sin SENTINEL | Baja | Medio | Mes 2 |
| MEDIO-003 | Sin rotación | Baja | Medio | Mes 2 |
---
## Plan de Remediación
### Semana 1 (Urgente)
- [ ] Activar UFW en CORP y HST
- [ ] chmod 600 en todos los .env
- [ ] Instalar fail2ban
- [ ] PostgreSQL bind 127.0.0.1
### Mes 1 (Alta)
- [ ] Migrar secretos a Infisical
- [ ] TLS interno
- [ ] Backup PostgreSQL automatizado
### Mes 2 (Media)
- [ ] SENTINEL LIGHT mode
- [ ] Política de rotación
- [ ] Monitoreo de certificados

292
04_SEGURIDAD/secretos.md Normal file
View File

@@ -0,0 +1,292 @@
# Gestión de Secretos TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Estado Actual: Triple Gestión
**PROBLEMA CRÍTICO:** Actualmente existen tres fuentes de secretos sin sincronización.
```
┌─────────────────────────────────────────────────────────────────┐
│ FUENTES DE SECRETOS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Infisical │ │ creds_* │ │ .env │ │
│ │ (central) │ │ (PostgreSQL)│ │ (archivos) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ❌ SIN SINCRONIZACIÓN - Riesgo de inconsistencia │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Fuente 1: Infisical
**URL:** http://localhost:8082 (ARCHITECT)
**Estado:** Operativo
### Configuración
```bash
# Acceso a Infisical
infisical login
infisical secrets --env=prod
```
### Ventajas
- Centralizado
- Versionado
- Auditable
- SDK para múltiples lenguajes
### Uso Actual
- Parcial - no todos los servicios lo usan
---
## Fuente 2: Tablas creds_* (PostgreSQL)
**Base de datos:** architect
**Estado:** Activo
### Tablas
| Tabla | Contenido |
|-------|-----------|
| creds_ia | APIs de IA (OpenAI, Anthropic, etc.) |
| creds_runpod | API keys de RunPod |
| creds_r2 | Credenciales Cloudflare R2 |
| creds_gitea | Tokens Gitea |
| creds_mail | Credenciales SMTP |
| creds_apis | APIs externas varias |
### Schema Típico
```sql
CREATE TABLE creds_ia (
id SERIAL PRIMARY KEY,
servicio VARCHAR(50) NOT NULL,
api_key TEXT NOT NULL,
descripcion TEXT,
activo BOOLEAN DEFAULT true,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
```
### Acceso
```sql
-- Consultar credenciales
sudo -u postgres psql -d architect -c "SELECT servicio, descripcion FROM creds_ia;"
```
---
## Fuente 3: Archivos .env
**Ubicaciones:**
- /opt/clara/.env
- /opt/alfred/.env
- /opt/margaret/.env
- /opt/mason/.env
- /opt/feldman/.env
### ALERTA CRÍTICA
```
Permisos actuales: 644 (legibles por todos)
Permisos correctos: 600 (solo propietario)
```
### Contenido Típico
```bash
# Ejemplo .env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=corp
DB_USER=margaret
DB_PASSWORD=secreto_aqui # ⚠️ Expuesto si 644
R2_ACCESS_KEY=access_key_aqui
R2_SECRET_KEY=secret_key_aqui # ⚠️ Expuesto si 644
```
---
## Decisión D-001: Migración a Infisical
### Objetivo
Infisical como **única fuente de verdad** para todos los secretos.
### Plan de Migración
```
Fase 1: Inventario
├── Catalogar todos los secretos en creds_*
├── Catalogar todos los secretos en .env
└── Identificar duplicados/inconsistencias
Fase 2: Centralización
├── Migrar todos los secretos a Infisical
├── Organizar por proyecto/ambiente
└── Establecer políticas de acceso
Fase 3: Actualización de Servicios
├── CLARA: Usar Infisical SDK
├── MARGARET: Usar Infisical SDK
├── MASON: Usar Infisical SDK
├── FELDMAN: Usar Infisical SDK
└── ALFRED/JARED: Usar Infisical SDK
Fase 4: Deprecación
├── Eliminar archivos .env
├── Marcar creds_* como "solo referencia"
└── Documentar proceso de rotación
```
### Implementación con SDK
```python
from infisical_client import InfisicalClient
client = InfisicalClient(
host="http://localhost:8082",
token=INFISICAL_TOKEN
)
# Obtener secreto
db_password = client.get_secret(
secret_name="DB_PASSWORD",
project_id="tzzr",
environment="production"
)
```
---
## Rotación de Secretos
### Política Propuesta
| Tipo | Frecuencia | Responsable |
|------|------------|-------------|
| API Keys externas | 90 días | Orchestrator |
| Contraseñas DB | 180 días | DBA |
| SSH Keys | 365 días | SysAdmin |
| Tokens Gitea | 180 días | DevOps |
### Proceso de Rotación
```
1. Generar nuevo secreto
2. Actualizar en Infisical
3. Desplegar servicios afectados
4. Verificar funcionamiento
5. Revocar secreto anterior
6. Documentar en changelog
```
---
## Mitigación Inmediata
### Paso 1: Permisos .env
```bash
# Ejecutar en todos los servidores
# DECK
ssh -i ~/.ssh/tzzr root@72.62.1.113 'chmod 600 /opt/clara/.env /opt/alfred/.env'
# CORP
ssh -i ~/.ssh/tzzr root@92.112.181.188 'chmod 600 /opt/margaret/.env /opt/mason/.env /opt/feldman/.env'
```
### Paso 2: Auditoría
```bash
# Verificar permisos
ls -la /opt/*/.env
# Buscar secretos expuestos
grep -r "password\|secret\|key" /opt/*/ 2>/dev/null
```
---
## Inventario de Secretos
### APIs de IA
| Servicio | Ubicación Actual | Notas |
|----------|------------------|-------|
| OpenAI | creds_ia | GPT-4 |
| Anthropic | creds_ia | Claude |
| Replicate | creds_ia | Modelos varios |
| RunPod | creds_runpod | GRACE, PENNY, FACTORY |
### Infraestructura
| Servicio | Ubicación Actual | Notas |
|----------|------------------|-------|
| PostgreSQL | .env + creds_* | Múltiples usuarios |
| R2/Cloudflare | .env + creds_r2 | Access + Secret key |
| Gitea | .env + creds_gitea | Read + Write tokens |
| SMTP | creds_mail | Mailcow |
### Servicios Externos
| Servicio | Ubicación Actual | Notas |
|----------|------------------|-------|
| Stripe | creds_apis | (si aplica) |
| Twilio | creds_apis | (si aplica) |
| AWS | creds_apis | (si aplica) |
---
## Verificación de Seguridad
### Checklist Diario
- [ ] Permisos .env son 600
- [ ] No hay secretos en logs
- [ ] No hay secretos en commits git
- [ ] Infisical accesible
### Comandos de Verificación
```bash
# Verificar permisos
find /opt -name ".env" -exec ls -la {} \;
# Buscar secretos en git history
git log -p | grep -i "password\|secret\|key\|token"
# Verificar Infisical
curl -s http://localhost:8082/api/v1/health
```
---
## Buenas Prácticas
### DO (Hacer)
- Usar Infisical para todos los secretos nuevos
- Rotar secretos según política
- Auditar accesos regularmente
- Cifrar secretos en reposo
### DON'T (No Hacer)
- Hardcodear secretos en código
- Commitear .env a repositorios
- Compartir secretos por chat/email
- Usar el mismo secreto en múltiples servicios

359
05_OPERACIONES/backup-recovery.md Normal file
View File

@@ -0,0 +1,359 @@
# Backup y Recovery TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Estado Actual
### Backups Existentes
| Sistema | Backup | Destino | Frecuencia | Estado |
|---------|--------|---------|------------|--------|
| Gitea | Sí | R2 | Manual | Operativo |
| PostgreSQL ARCHITECT | No | - | - | **CRÍTICO** |
| PostgreSQL DECK | No | - | - | **CRÍTICO** |
| PostgreSQL CORP | No | - | - | **CRÍTICO** |
| PostgreSQL HST | No | - | - | **CRÍTICO** |
| R2 buckets | Built-in | R2 | Automático | Operativo |
---
## Plan de Backup Propuesto
### PostgreSQL - Backup Diario
```bash
#!/bin/bash
# /opt/scripts/backup_postgres.sh
set -e
DATE=$(date +%F)
BACKUP_DIR="/tmp/pg_backup"
# Cargar credenciales R2
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
R2_ENDPOINT="https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com"
mkdir -p $BACKUP_DIR
# Backup ARCHITECT
echo "Backing up ARCHITECT..."
sudo -u postgres pg_dump architect | gzip > $BACKUP_DIR/architect_$DATE.sql.gz
aws s3 cp $BACKUP_DIR/architect_$DATE.sql.gz s3://architect/backups/postgres/ \
--endpoint-url $R2_ENDPOINT
# Cleanup local
rm -rf $BACKUP_DIR
echo "Backup completado: $DATE"
```
### Cron Configuration
```bash
# /etc/cron.d/tzzr-backup
# Backup diario a las 3:00 AM
0 3 * * * orchestrator /opt/scripts/backup_postgres.sh >> /var/log/tzzr-backup.log 2>&1
```
---
## Backup por Servidor
### ARCHITECT (69.62.126.110)
```bash
# Base de datos: architect
sudo -u postgres pg_dump architect | gzip > architect_$(date +%F).sql.gz
# Subir a R2
aws s3 cp architect_$(date +%F).sql.gz s3://architect/backups/postgres/ \
--endpoint-url $R2_ENDPOINT
```
### DECK (72.62.1.113)
```bash
# Base de datos: tzzr
ssh deck 'sudo -u postgres pg_dump tzzr | gzip' > deck_tzzr_$(date +%F).sql.gz
# Subir a R2
aws s3 cp deck_tzzr_$(date +%F).sql.gz s3://architect/backups/deck/ \
--endpoint-url $R2_ENDPOINT
```
### CORP (92.112.181.188)
```bash
# Base de datos: corp
ssh corp 'sudo -u postgres pg_dump corp | gzip' > corp_$(date +%F).sql.gz
# Subir a R2
aws s3 cp corp_$(date +%F).sql.gz s3://architect/backups/corp/ \
--endpoint-url $R2_ENDPOINT
```
### HST (72.62.2.84)
```bash
# Base de datos: hst_images
ssh hst 'sudo -u postgres pg_dump hst_images | gzip' > hst_$(date +%F).sql.gz
# Subir a R2
aws s3 cp hst_$(date +%F).sql.gz s3://architect/backups/hst/ \
--endpoint-url $R2_ENDPOINT
```
---
## Gitea Backup
### Backup Manual
```bash
# En ARCHITECT
docker exec -t gitea bash -c 'gitea dump -c /data/gitea/conf/app.ini'
docker cp gitea:/app/gitea/gitea-dump-*.zip ./
# Subir a R2
aws s3 cp gitea-dump-*.zip s3://architect/backups/gitea/ \
--endpoint-url $R2_ENDPOINT
```
### Backup Automático
```bash
#!/bin/bash
# /opt/scripts/backup_gitea.sh
DATE=$(date +%F_%H%M)
# Crear dump
docker exec -t gitea bash -c "gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump-$DATE.zip"
# Copiar fuera del container
docker cp gitea:/tmp/gitea-dump-$DATE.zip /tmp/
# Subir a R2
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
aws s3 cp /tmp/gitea-dump-$DATE.zip s3://architect/backups/gitea/ \
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
# Cleanup
rm /tmp/gitea-dump-$DATE.zip
docker exec gitea rm /tmp/gitea-dump-$DATE.zip
```
---
## Estructura de Backups en R2
```
s3://architect/backups/
├── postgres/
│ ├── architect_2024-12-24.sql.gz
│ ├── architect_2024-12-23.sql.gz
│ └── ...
├── deck/
│ ├── deck_tzzr_2024-12-24.sql.gz
│ └── ...
├── corp/
│ ├── corp_2024-12-24.sql.gz
│ └── ...
├── hst/
│ ├── hst_2024-12-24.sql.gz
│ └── ...
└── gitea/
├── gitea-dump-2024-12-24_0300.zip
└── ...
```
---
## Retención de Backups
### Política Propuesta
| Tipo | Retención | Notas |
|------|-----------|-------|
| Diario | 7 días | Últimos 7 backups |
| Semanal | 4 semanas | Domingos |
| Mensual | 12 meses | Primer día del mes |
### Script de Limpieza
```bash
#!/bin/bash
# /opt/scripts/cleanup_backups.sh
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
R2_ENDPOINT="https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com"
# Eliminar backups más antiguos de 30 días
# (Implementar con lifecycle rules de R2 preferentemente)
aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \
while read -r line; do
createDate=$(echo $line | awk '{print $1}')
fileName=$(echo $line | awk '{print $4}')
# Comparar fechas y eliminar si > 30 días
# ...
done
```
---
## Recovery
### PostgreSQL - Restaurar Base de Datos
```bash
# Descargar backup
aws s3 cp s3://architect/backups/postgres/architect_2024-12-24.sql.gz . \
--endpoint-url $R2_ENDPOINT
# Descomprimir
gunzip architect_2024-12-24.sql.gz
# Restaurar (¡CUIDADO! Sobrescribe datos existentes)
sudo -u postgres psql -d architect < architect_2024-12-24.sql
```
### PostgreSQL - Restaurar a Nueva Base
```bash
# Crear nueva base de datos
sudo -u postgres createdb architect_restored
# Restaurar
gunzip -c architect_2024-12-24.sql.gz | sudo -u postgres psql -d architect_restored
```
### Gitea - Restaurar
```bash
# Descargar backup
aws s3 cp s3://architect/backups/gitea/gitea-dump-2024-12-24_0300.zip . \
--endpoint-url $R2_ENDPOINT
# Detener Gitea
docker stop gitea
# Copiar al container
docker cp gitea-dump-2024-12-24_0300.zip gitea:/tmp/
# Restaurar
docker exec gitea bash -c "cd /tmp && unzip gitea-dump-2024-12-24_0300.zip"
# Seguir instrucciones de Gitea para restore
# Iniciar Gitea
docker start gitea
```
---
## Disaster Recovery Plan
### Escenario 1: Pérdida de ARCHITECT
1. Provisionar nuevo VPS con misma IP (si posible)
2. Instalar Ubuntu 22.04
3. Configurar usuario orchestrator
4. Restaurar PostgreSQL desde R2
5. Restaurar Gitea desde R2
6. Reinstalar Docker y servicios
7. Verificar conectividad con DECK/CORP/HST
### Escenario 2: Pérdida de DECK
1. Provisionar nuevo VPS
2. Restaurar PostgreSQL (tzzr) desde backup
3. Reinstalar CLARA, ALFRED
4. Reinstalar Mailcow (requiere backup separado)
5. Actualizar DNS si IP cambió
### Escenario 3: Pérdida de CORP
1. Provisionar nuevo VPS
2. Restaurar PostgreSQL (corp) desde backup
3. Reinstalar MARGARET, JARED, MASON, FELDMAN
4. Reinstalar Odoo, Nextcloud
5. Activar UFW (nuevo servidor)
### Escenario 4: Pérdida de R2
**IMPROBABLE** - Cloudflare tiene redundancia multi-región.
Mitigación: Backup mensual a segundo proveedor (AWS S3 Glacier).
---
## Verificación de Backups
### Test Mensual
```bash
#!/bin/bash
# /opt/scripts/verify_backup.sh
# Descargar último backup
LATEST=$(aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \
sort | tail -1 | awk '{print $4}')
aws s3 cp s3://architect/backups/postgres/$LATEST /tmp/ \
--endpoint-url $R2_ENDPOINT
# Verificar integridad
gunzip -t /tmp/$LATEST
if [ $? -eq 0 ]; then
echo "Backup válido: $LATEST"
else
echo "ERROR: Backup corrupto: $LATEST"
# Enviar alerta
fi
rm /tmp/$LATEST
```
### Checklist de Verificación
- [ ] Backup PostgreSQL ARCHITECT existe (< 24h)
- [ ] Backup PostgreSQL DECK existe (< 24h)
- [ ] Backup PostgreSQL CORP existe (< 24h)
- [ ] Backup Gitea existe (< 7d)
- [ ] Integridad verificada (gunzip -t)
- [ ] Restore test exitoso (mensual)
---
## Alertas
### Configuración ntfy
```bash
# Notificar si backup falla
if [ $? -ne 0 ]; then
curl -d "Backup FALLIDO: $DATE" ntfy.sh/tzzr-alerts
fi
```
### Monitoreo
```bash
# Verificar último backup
aws s3 ls s3://architect/backups/postgres/ --endpoint-url $R2_ENDPOINT | \
sort | tail -5
```

383
05_OPERACIONES/infraestructura.md Normal file
View File

@@ -0,0 +1,383 @@
# Infraestructura TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Resumen de Servidores
| Servidor | IP Pública | Rol | Proveedor |
|----------|------------|-----|-----------|
| ARCHITECT | 69.62.126.110 | Coordinador central | VPS |
| DECK | 72.62.1.113 | Personal | VPS |
| CORP | 92.112.181.188 | Empresarial | VPS |
| HST | 72.62.2.84 | API Tags | VPS |
| LOCKER | R2 | Almacenamiento | Cloudflare |
---
## ARCHITECT (69.62.126.110)
### Especificaciones
- **OS:** Ubuntu 22.04 LTS
- **Usuario:** orchestrator
- **Servicios:** PostgreSQL, Gitea, Orchestrator, Infisical
### Puertos
| Puerto | Servicio | Estado |
|--------|----------|--------|
| 22 | SSH | Abierto |
| 2222 | Gitea SSH | Abierto |
| 3000 | Gitea HTTP | Abierto |
| 5050 | Orchestrator | Abierto |
| 5432 | PostgreSQL | **CRÍTICO: 0.0.0.0** |
| 8082 | Infisical | Abierto |
### Acceso
```bash
ssh orchestrator@69.62.126.110
```
### PostgreSQL
```bash
sudo -u postgres psql -d architect
```
### Gitea
```
URL: http://localhost:3000
Token lectura: 5ca10e5b71d41f9b22f12d0f96bfc2e6de5c2c7f
Token escritura: ac5a604b9aac5cee81192a656fc918f9efa3834b
```
---
## DECK (72.62.1.113)
### Especificaciones
- **OS:** Ubuntu 22.04 LTS
- **Usuario:** root
- **Servicios:** CLARA, ALFRED, Mailcow, Directus, etc.
### Puertos
| Puerto | Servicio | Estado |
|--------|----------|--------|
| 22 | SSH | Abierto |
| 25 | SMTP | Abierto |
| 143 | IMAP | Abierto |
| 465 | SMTPS | Abierto |
| 587 | Submission | Abierto |
| 993 | IMAPS | Abierto |
| 5051 | CLARA | Abierto |
| 5052 | ALFRED | Abierto |
| 8055 | Directus | Abierto |
| 8080 | ntfy | Abierto |
| 8082 | FileBrowser | Abierto |
| 8083 | Shlink | Abierto |
| 8085 | Vaultwarden | Abierto |
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113
```
### Docker Containers
```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```
---
## CORP (92.112.181.188)
### Especificaciones
- **OS:** Ubuntu 22.04 LTS
- **Usuario:** root
- **Servicios:** MARGARET, JARED, MASON, FELDMAN, Odoo, Nextcloud
### Puertos
| Puerto | Servicio | Estado |
|--------|----------|--------|
| 22 | SSH | Abierto |
| 80 | Caddy HTTP | Abierto |
| 443 | Caddy HTTPS | Abierto |
| 5051 | MARGARET | Abierto |
| 5052 | JARED | Abierto |
| 5053 | MASON | Abierto |
| 5054 | FELDMAN | Abierto |
| 5432 | PostgreSQL | Local |
| 8055 | Directus | Abierto |
| 8069 | Odoo | Abierto |
| 8080 | Nextcloud | Abierto |
| 8081 | Vaultwarden | Abierto |
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@92.112.181.188
```
### Firewall
**ALERTA CRÍTICA: UFW INACTIVO**
```bash
# Verificar estado
ufw status
# Activar (cuando se autorice)
ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
```
---
## HST (72.62.2.84)
### Especificaciones
- **OS:** Ubuntu 22.04 LTS
- **Usuario:** root
- **Servicios:** Nginx, Directus, PostgreSQL
### Puertos
| Puerto | Servicio | Estado |
|--------|----------|--------|
| 22 | SSH | Abierto |
| 80 | Nginx HTTP | Abierto |
| 443 | Nginx HTTPS | Abierto |
| 5432 | PostgreSQL | Local |
| 8055 | Directus | Abierto |
### Acceso
```bash
ssh -i ~/.ssh/tzzr root@72.62.2.84
```
### API Pública
```
https://tzrtech.org/{h_maestro}.png
```
### Estadísticas HST
| Grupo | Cantidad |
|-------|----------|
| hst | 639 |
| spe | 145 |
| vsn | 84 |
| flg | 65 |
| vue | 21 |
| **Total** | **973** |
---
## LOCKER (Cloudflare R2)
### Endpoint
```
https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```
### Buckets
| Bucket | Uso | Tamaño Aprox |
|--------|-----|--------------|
| architect | Backups, configs, GPU services | ~500 MB |
| deck | Archivos personales (CLARA) | Variable |
| corp | Archivos empresariales (MARGARET) | Variable |
| hst | Imágenes de tags | ~100 MB |
| locker | Almacenamiento general | Variable |
### Acceso
```bash
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
aws s3 ls s3://architect/ \
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```
---
## SSH Keys
### Ubicación
```
/home/orchestrator/.ssh/tzzr # Private key
/home/orchestrator/.ssh/tzzr.pub # Public key
```
### Permisos
```bash
chmod 600 ~/.ssh/tzzr
chmod 644 ~/.ssh/tzzr.pub
```
### Configuración SSH
```bash
# ~/.ssh/config
Host deck
HostName 72.62.1.113
User root
IdentityFile ~/.ssh/tzzr
Host corp
HostName 92.112.181.188
User root
IdentityFile ~/.ssh/tzzr
Host hst
HostName 72.62.2.84
User root
IdentityFile ~/.ssh/tzzr
```
---
## Bases de Datos
### architect (ARCHITECT)
```
Host: localhost
Port: 5432
Database: architect
User: postgres
```
Tablas principales:
- context_blocks
- agents
- creds_*
### tzzr (DECK)
```
Host: localhost
Port: 5432
Database: tzzr
```
Tablas principales:
- clara_log
- deck_visiones
- deck_milestones
### corp (CORP)
```
Host: localhost
Port: 5432
Database: corp
```
Tablas principales:
- margaret_log
- mason_workspace
- feldman_cola
- milestones
- bloques
### hst_images (HST)
```
Host: localhost
Port: 5432
Database: hst_images
```
Tablas principales:
- hst_tags
- hst_trees
---
## Monitoreo
### Comandos de Estado
```bash
# Verificar servicios ARCHITECT
systemctl status postgresql
docker ps
# Verificar servicios DECK
ssh deck 'docker ps'
ssh deck 'systemctl status fail2ban'
# Verificar servicios CORP
ssh corp 'docker ps'
ssh corp 'ufw status'
# Verificar servicios HST
ssh hst 'systemctl status nginx'
ssh hst 'systemctl status postgresql'
```
### Logs Importantes
```bash
# PostgreSQL
journalctl -u postgresql -f
# Docker containers
docker logs <container> -f
# Nginx (HST)
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
# SSH auth
tail -f /var/log/auth.log
```
---
## Diagrama de Red
```
Internet
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ ARCHITECT │ │ DECK │ │ CORP │
│ 69.62.126.110 │◄────────│ 72.62.1.113 │────────►│92.112.181.188 │
└───────────────┘ SSH └───────────────┘ SSH └───────────────┘
│ │ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ HST │ │
└────────────────►│ 72.62.2.84 │◄──────────────────┘
SSH └───────────────┘
│
│ HTTPS
▼
┌───────────────┐
│ Cloudflare │
│ R2 │
└───────────────┘
```

179
06_INTEGRACIONES/gpu-services.md Normal file
View File

@@ -0,0 +1,179 @@
# GPU Services - RunPod
**Versión:** 5.0
**Fecha:** 2024-12-24
---
## Estado Crítico
**ALERTA: RunPod NO es confiable para producción.**
### Incidente 2024-12-24
RunPod falló en provisionar workers a pesar de:
- Configuración correcta
- Balance suficiente ($72+)
- Jobs en cola
**Resultado:** 0 workers activos. Servicio GPU inoperativo.
---
## Endpoints Configurados
| Servicio | Endpoint ID | Estado |
|----------|-------------|--------|
| GRACE | r00x4g3rrwkbyh | Inactivo |
| PENNY | 0mxhaokgsmgee3 | Inactivo |
| FACTORY | ddnuk6y35zi56a | Inactivo |
---
## GRACE (Extracción IA)
### Módulos Implementados (6 de 18)
| Módulo | Descripción |
|--------|-------------|
| ASR | Speech-to-text |
| OCR | Reconocimiento texto |
| TTS | Text-to-speech |
| Face | Reconocimiento facial |
| Embeddings | Vectores semánticos |
| Avatar | Generación avatares |
### Módulos Pendientes (12)
- Document parsing
- Image classification
- Object detection
- Sentiment analysis
- Named entity recognition
- Translation
- Summarization
- Question answering
- Code generation
- Audio classification
- Video analysis
- Multimodal fusion
---
## Código Disponible en R2
Los handlers están listos y son portables:
```
s3://architect/gpu-services/
├── base/
│ └── bootstrap.sh
├── grace/
│ └── code/handler.py
├── penny/
│ └── code/handler.py
└── factory/
└── code/handler.py
```
### Descargar Código
```bash
source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"
aws s3 sync s3://architect/gpu-services/ ./gpu-services/ \
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```
---
## Alternativas a Evaluar
### 1. Modal (Recomendado)
- Pricing: Pay-per-use
- Pros: Serverless real, buen DX, Python-native
- Contras: Menos GPUs disponibles que RunPod
```python
import modal
stub = modal.Stub("grace")
@stub.function(gpu="A10G")
def process_asr(audio_bytes):
# Whisper inference
pass
```
### 2. Replicate
- Pricing: Per-inference
- Pros: Modelos pre-entrenados, API simple
- Contras: Menos control, más caro a escala
### 3. Lambda Labs
- Pricing: Hourly
- Pros: Hardware dedicado
- Contras: Menos flexible, reserva manual
### 4. Self-Hosted
- Pricing: Upfront + hosting
- Pros: Control total, sin dependencias
- Contras: CapEx alto, mantenimiento
---
## Migración Propuesta
### Fase 1: Evaluación (1 semana)
- [ ] Probar Modal con ASR handler
- [ ] Comparar latencia y costo
### Fase 2: Migración (2 semanas)
- [ ] Portar 6 handlers a Modal
- [ ] Actualizar endpoints en MASON
### Fase 3: Producción
- [ ] Desplegar en Modal
- [ ] Deprecar RunPod endpoints
---
## Configuración Actual RunPod
### API Key
```
Almacenada en: creds_runpod (PostgreSQL ARCHITECT)
Campo: api_key_runpod
```
### SDK
```python
import runpod
runpod.api_key = "..."
# Crear job
job = runpod.run(
endpoint_id="r00x4g3rrwkbyh",
input={"audio": "base64..."}
)
# Check status
status = runpod.status(job["id"])
```
---
## Recomendación
**NO confiar en RunPod para producción.**
Migrar a Modal como prioridad alta una vez resueltos los issues de seguridad críticos.

387
99_ANEXOS/inventario-repos.md Normal file
View File

@@ -0,0 +1,387 @@
# Inventario de Repositorios TZZR
**Versión:** 5.0
**Fecha:** 2024-12-24
**Fuente:** Gitea (http://localhost:3000/tzzr)
---
## Resumen
| Categoría | Cantidad |
|-----------|----------|
| Infraestructura | 6 |
| Data Services | 6 |
| Security/Ops | 6 |
| Interfaces | 6 |
| **Total** | **24** |
---
## Infraestructura
### orchestrator
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/orchestrator |
| Estado | Activo |
| Descripción | Sistema de orquestación central |
| Prioridad | Alta |
**Archivos clave:**
- `main.py` - Entrada principal
- `.env` - Configuración
- `docker-compose.yml` - Despliegue
---
### hst-api
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/hst-api |
| Estado | Activo |
| Descripción | API de tags HST (973 tags) |
| Prioridad | Alta |
**Archivos clave:**
- `api/routes.py` - Endpoints
- `db/schema.sql` - Schema
---
### clara
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/clara |
| Estado | Activo |
| Descripción | Agente de ingesta personal |
| Prioridad | Alta |
**Archivos clave:**
- `app.py` - API FastAPI
- `ingest.py` - Lógica de ingesta
- `Dockerfile` - Container
---
### margaret
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/margaret |
| Estado | Activo |
| Descripción | Agente de ingesta corporativo |
| Prioridad | Alta |
**Archivos clave:**
- `app.py` - API FastAPI
- `ingest.py` - Lógica de ingesta
- `Dockerfile` - Container
---
### alfred
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/alfred |
| Estado | Activo |
| Descripción | Flujos predefinidos DECK |
| Prioridad | Media |
**Archivos clave:**
- `flows/` - Definiciones de flujos
- `executor.py` - Motor de ejecución
---
### jared
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/jared |
| Estado | Activo |
| Descripción | Flujos predefinidos CORP |
| Prioridad | Media |
**Archivos clave:**
- `flows/` - Definiciones de flujos
- `executor.py` - Motor de ejecución
---
## Data Services
### mason
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/mason |
| Estado | Activo |
| Descripción | Enriquecimiento de datos |
| Prioridad | Alta |
**Archivos clave:**
- `workspace.py` - Gestión workspace
- `enrichment.py` - Lógica de enriquecimiento
---
### feldman
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/feldman |
| Estado | Activo |
| Descripción | Consolidación blockchain |
| Prioridad | Alta |
**Archivos clave:**
- `validator.py` - Reglas M-001, M-002, M-003
- `consolidator.py` - Creación de bloques
---
### grace-handler
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/grace-handler |
| Estado | Bloqueado (RunPod) |
| Descripción | Handler GPU para GRACE |
| Prioridad | Alta |
**Archivos clave:**
- `handler.py` - RunPod handler
- `modules/` - 6 módulos IA
---
### penny-handler
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/penny-handler |
| Estado | Planificado |
| Descripción | Handler GPU para PENNY |
| Prioridad | Baja |
---
### factory-handler
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/factory-handler |
| Estado | Planificado |
| Descripción | Handler GPU para FACTORY |
| Prioridad | Baja |
---
### s-contract
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/s-contract |
| Estado | En desarrollo |
| Descripción | Contextos y datasets IA |
| Prioridad | Media |
---
## Security/Ops
### sentinel
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/sentinel |
| Estado | Planificado |
| Descripción | Auditoría del sistema |
| Prioridad | Media |
**Modos:**
- LIGHT: Cada 5 min, reglas automáticas
- DEEP: Cada 1 hora, muestreo con LLM
---
### infisical-config
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/infisical-config |
| Estado | Activo |
| Descripción | Configuración Infisical |
| Prioridad | Alta |
---
### backup-scripts
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/backup-scripts |
| Estado | En desarrollo |
| Descripción | Scripts de backup R2 |
| Prioridad | Alta |
---
### deploy-configs
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/deploy-configs |
| Estado | Activo |
| Descripción | Configuraciones de despliegue |
| Prioridad | Media |
---
### monitoring
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/monitoring |
| Estado | Planificado |
| Descripción | Dashboards y alertas |
| Prioridad | Media |
---
### security-audit
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/security-audit |
| Estado | En desarrollo |
| Descripción | Scripts de auditoría |
| Prioridad | Alta |
---
## Interfaces
### packet-app
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/packet-app |
| Estado | En desarrollo |
| Descripción | App móvil Flutter |
| Prioridad | Alta |
**Tecnología:** Flutter/Dart
---
### vision-builder
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/vision-builder |
| Estado | En desarrollo |
| Descripción | Diseñador de visiones |
| Prioridad | Media |
---
### admin-dashboard
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/admin-dashboard |
| Estado | Planificado |
| Descripción | Dashboard administrativo |
| Prioridad | Baja |
---
### api-gateway
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/api-gateway |
| Estado | Planificado |
| Descripción | Gateway API unificado |
| Prioridad | Media |
---
### docs-site
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/docs-site |
| Estado | En desarrollo |
| Descripción | Sitio de documentación |
| Prioridad | Media |
---
### system-docs
| Campo | Valor |
|-------|-------|
| URL | http://localhost:3000/tzzr/system-docs |
| Estado | Activo (este repo) |
| Descripción | Documentación System v5 |
| Prioridad | Alta |
---
## Estadísticas
### Por Estado
| Estado | Cantidad |
|--------|----------|
| Activo | 12 |
| En desarrollo | 6 |
| Planificado | 5 |
| Bloqueado | 1 |
### Por Prioridad
| Prioridad | Cantidad |
|-----------|----------|
| Alta | 12 |
| Media | 8 |
| Baja | 4 |
---
## Dependencias Entre Repos
```
packet-app
│
▼
clara / margaret
│
▼
alfred / jared
│
▼
mason ◄──── grace-handler (bloqueado)
│
▼
feldman
│
▼
sentinel (planificado)
```
---
## Notas
1. **grace-handler**: Código listo en R2, RunPod no inicia workers
2. **sentinel**: Solo documentación, sin implementación
3. **system-docs**: Este repositorio, documentación v5
4. **orchestrator**: Coordinador central en ARCHITECT

121
README.md
View File

@@ -1,3 +1,120 @@
# system-docs # TZZR System Documentation v5
Documentación oficial del sistema TZZR - System v5 **Versión:** 5.0
**Fecha:** 2024-12-24
**Estado:** Consolidación completa
---
## Qué es TZZR
TZZR es un sistema de construcción de arquitecturas personales y empresariales mediante instancias Claude. Los agentes IA actúan como constructores que diseñan y edifican servidores clonables e independientes.
---
## Arquitectura General
```
┌─────────────────────────────────────────────────────────────┐
│ ARCHITECT (69.62.126.110) │
│ PostgreSQL central │ Gitea │ Orchestrator │ Infisical │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ DECK │ │ CORP │ │ HST │
│ 72.62.1.113 │ │ 92.112.181.188 │ │ 72.62.2.84 │
│ │ │ │ │ │
│ CLARA, ALFRED │ │ MARGARET, JARED │ │ 973 tags │
│ Servidor │ │ MASON, FELDMAN │ │ API pública │
│ Personal │ │ Empresarial │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
└────────┬───────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare R2 (5 buckets) │
│ architect │ deck │ corp │ hst │ locker │
└─────────────────────────────────────────────────────────────┘
```
---
## Flujo de Datos Principal
```
PACKET (móvil)
↓
CLARA (DECK) / MARGARET (CORP) ← Ingesta inmutable
↓
ALFRED / JARED ← Flujos predefinidos
↓
MASON ← Enriquecimiento (24h)
↓
FELDMAN ← Consolidación blockchain
↓
SENTINEL ← Auditoría (planificado)
```
---
## Índice de Documentación
### 00_VISION
- [Filosofía](00_VISION/filosofia.md) - 10 principios fundacionales
- [Glosario](00_VISION/glosario.md) - Términos técnicos A-Z
### 01_ARQUITECTURA
- [Overview](01_ARQUITECTURA/overview.md) - Vista general consolidada
- [Servidores](01_ARQUITECTURA/servidores.md) - ARCHITECT, DECK, CORP, HST
### 02_MODELO_DATOS
- [Entidades](02_MODELO_DATOS/entidades.md) - HST, ITM, PLY, LOC, FLG
- [Planos](02_MODELO_DATOS/planos.md) - T0 (ITM), MST, BCK
### 03_COMPONENTES
- [CLARA/MARGARET](03_COMPONENTES/agentes/clara-margaret.md) - Ingesta
- [FELDMAN](03_COMPONENTES/agentes/feldman.md) - Consolidación
- [GRACE](03_COMPONENTES/servicios/grace.md) - IA cognitiva
### 04_SEGURIDAD
- [Modelo de Amenazas](04_SEGURIDAD/modelo-amenazas.md) - Riesgos
- [Secretos](04_SEGURIDAD/secretos.md) - Gestión credenciales
### 05_OPERACIONES
- [Infraestructura](05_OPERACIONES/infraestructura.md) - Servidores
- [Backup/Recovery](05_OPERACIONES/backup-recovery.md) - DR plan
### 06_INTEGRACIONES
- [GPU Services](06_INTEGRACIONES/gpu-services.md) - RunPod
### 99_ANEXOS
- [Inventario Repos](99_ANEXOS/inventario-repos.md) - 24 repos
---
## Estado Actual
| Componente | Estado | Notas |
|------------|--------|-------|
| CLARA | Operativo | DECK:5051 |
| MARGARET | Operativo | CORP:5051 |
| ALFRED | Operativo | DECK:5052 |
| JARED | Operativo | CORP:5052 |
| MASON | Operativo | CORP:5053 |
| FELDMAN | Operativo | CORP:5054 |
| HST | Operativo | 973 tags |
| SENTINEL | Planificado | Sin implementar |
| GRACE | Bloqueado | RunPod no inicia |
| NOTARIO | Planificado | Sin implementar |
---
## Generación
Documentación generada mediante proceso de auditoría colaborativa:
- 3 auditores especializados (Arquitectura, Datos, Seguridad)
- Cross-review y resolución de conflictos
- Síntesis consolidada
**Fecha generación:** 2024-12-24