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

Update to Skynet v7 - Complete documentation restructure

Browse Source 
- Nueva estructura de carpetas según Skynet v7
- Añadidos schemas SQL completos
- Documentación de entidades, componentes e integraciones
- Modelo de seguridad actualizado
- Infraestructura y operaciones reorganizadas
This commit is contained in:
ARCHITECT
2025-12-29 18:23:41 +00:00
parent ac481fe266
commit 6ea70bd34f
76 changed files with 13029 additions and 4340 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
01_ARQUITECTURA/almacenamiento.md Normal file
View File

@@ -0,0 +1,128 @@
# Almacenamiento
**Versión:** 1.0
**Estado:** Definición
---
## Visión General
El sistema utiliza Cloudflare R2 como almacenamiento de objetos. Cada instancia tiene su propio bucket independiente.
---
## Buckets R2
| Bucket | Uso | Acceso |
|--------|-----|--------|
| **architect** | Coordinador central | Privado |
| **deck** | Servidor personal | Privado |
| **corp** | Servidor empresarial | Privado |
| **hst** | Tags semánticos (imágenes) | Público |
| **locker** | Almacenamiento general | Privado |
---
## Protocolo locker://
Referencia interna para archivos almacenados en R2.
### Formato
```
locker://{bucket}/{h_entrada}/{filename}
```
### Ejemplos
```
locker://deck/a1b2c3d4.../documento.pdf
locker://corp/f5e6d7c8.../factura.png
locker://hst/abc123.../imagen.png
```
---
## Estructura de Almacenamiento
### Por contenedor (ingesta)
```
{bucket}/
└── {h_entrada}/
├── archivo1.pdf
├── archivo2.jpg
└── metadata.json
```
### HST (tags)
```
hst/
└── {mrf}.png # mrf = SHA-256 del archivo de imagen
```
---
## Configuración R2
### Variables de Entorno
```bash
R2_ENDPOINT=https://{account_id}.r2.cloudflarestorage.com
R2_ACCESS_KEY=****
R2_SECRET_KEY=****
R2_BUCKET={bucket_name}
```
### Cliente Python
```python
import boto3
s3 = boto3.client(
's3',
endpoint_url=R2_ENDPOINT,
aws_access_key_id=R2_ACCESS_KEY,
aws_secret_access_key=R2_SECRET_KEY
)
# Subir archivo
s3.put_object(
Bucket=R2_BUCKET,
Key=f"{h_entrada}/{filename}",
Body=file_bytes
)
# Obtener archivo
response = s3.get_object(
Bucket=R2_BUCKET,
Key=f"{h_entrada}/{filename}"
)
content = response['Body'].read()
```
---
## Política de Retención
| Tipo de datos | Retención | Backup |
|---------------|-----------|--------|
| Archivos de ingesta | Permanente | Sí |
| Imágenes HST | Permanente | Sí |
| Temporales | 7 días | No |
---
## Integridad
Cada archivo se identifica por su hash SHA-256:
```python
import hashlib
def calcular_hash(contenido_bytes):
return hashlib.sha256(contenido_bytes).hexdigest()
```
La referencia `locker://` incluye el hash del contenedor, permitiendo verificación de integridad.

142
01_ARQUITECTURA/aplicaciones/mind-link.md Normal file
View File

@@ -0,0 +1,142 @@
# Mind Link
**Tipo:** Aplicación Web
**Versión:** v11
**Estado:** En desarrollo
---
## Descripción
Interfaz de comunicación visual tipo mindmap/linktree. Presenta nodos principales (categorías) con subnodos desplegables (documentos) conectados por líneas animadas.
---
## Arquitectura Visual
```
┌─────────────────────────────────────────────────────────────────┐
│ MIND LINK │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────────────┐ │
│ │ NODO │──────────────│ SUBNODO 1 │ │
│ │ 120x120 │ │ 180x101 │ │
│ │ │──────────────│ SUBNODO 2 │ │
│ └─────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Especificaciones Técnicas
### Dimensiones
| Elemento | Valor | Notas |
|----------|-------|-------|
| Nodo principal | 120×120 px | Cuadrado |
| Subnodo | 180×101 px | Ratio 16:9 |
| Radio esquinas nodo | 20px | |
| Radio esquinas subnodo | 15px | |
| Grosor líneas/bordes | 3px | |
| Gap entre subnodos | 20px | Vertical |
| Gap entre grupos | 50px | Vertical |
| Gap nodo a subnodo | 70px | Horizontal |
### Tipografía
| Elemento | Tamaño | Peso | Color |
|----------|--------|------|-------|
| Título página | 32px | 600 | #1a1a1a |
| Título nodo | 18px | 500 | Color del nodo |
| Título subnodo | 16px | 500 | Color del nodo |
### Colores por Defecto
```
#FF6B35 - Naranja (nodo 1)
#E5A000 - Amarillo (nodo 2)
#06D6A0 - Verde (nodo 3)
#0891B2 - Cyan (nodo 4)
#3B82F6 - Azul (nodo 5)
#8B5CF6 - Violeta (nodo 6)
#EC4899 - Rosa (nodo 7)
```
---
## Iconos de Acción
Posicionados en las 4 esquinas del subnodo:
```
┌─────────────────────┐
│ 🕐 👁 │ 🕐 = historial
│ │ 👁 = preview
│ │
│ ⬇ 🔗 │ ⬇ = descarga
└─────────────────────┘ 🔗 = enlace
```
| Icono | Campo | Función |
|-------|-------|---------|
| 👁 | tiene_preview | Abrir modal con documento |
| ⬇ | tiene_descarga | Descargar archivo |
| 🔗 | tiene_enlace | Copiar URL |
| 🕐 | tiene_historial | Mostrar versiones |
---
## Animaciones
| Elemento | Duración | Función | Delay |
|----------|----------|---------|-------|
| Movimiento vertical nodo | 400ms | ease-out | - |
| Revelado de líneas | 450ms | linear | 80ms |
| Aparición subnodos | instantánea | - | 30ms |
---
## Estructura de Datos
### Configuración
| Campo | Tipo | Descripción |
|-------|------|-------------|
| titulo | String | Título principal |
| mostrar_titulo | Boolean | Mostrar/ocultar |
| colores | String | Hex separados por comas |
| fuente | String | Nombre de fuente |
### Nodos
| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | String | Identificador único |
| titulo | String | Nombre categoría |
| imagen | URL | Imagen 120×120 |
| subnodos | Array | Lista documentos |
### Subnodos
| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | String | Identificador único |
| titulo | String | Nombre documento |
| imagen | URL | Miniatura 16:9 |
| tiene_preview | Boolean | Icono ojo |
| tiene_descarga | Boolean | Icono descarga |
| tiene_enlace | Boolean | Icono enlace |
| tiene_historial | Boolean | Icono reloj |
---
## Pendiente
- [ ] Conexión real con API
- [ ] Sistema de autenticación con PIN
- [ ] Funcionalidad real de iconos
- [ ] Responsive móvil
- [ ] Integración en aplicación empresarial

74
01_ARQUITECTURA/aplicaciones/packet.md Normal file
View File

@@ -0,0 +1,74 @@
# Packet
**Tipo:** App Móvil
**Estado:** En desarrollo
---
## Descripción
App móvil de captura multimedia con política **zero-retention**. No almacena datos localmente; todo va directo al servidor.
---
## Principio
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ PACKET no almacena datos localmente. │
│ Todo va directo al servidor. │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Flujo
```
Captura (foto/audio/texto)
│
▼
Upload inmediato
│
▼
Clara/Margaret (secretaría)
│
▼
Confirmación al usuario
│
▼
Borrado local
```
---
## Tipos de Captura
| Tipo | Formato | Uso |
|------|---------|-----|
| **Foto** | JPEG/PNG | Evidencia visual |
| **Audio** | MP3/WAV | Notas de voz |
| **Texto** | String | Notas rápidas |
| **Ubicación** | Coords | Geolocalización |
---
## Características
| Característica | Valor |
|----------------|-------|
| Almacenamiento local | NO |
| Funciona offline | NO (requiere conexión) |
| Autenticación | Token de sesión |
| Destino | Secretaría (Clara/Margaret) |
---
## Integración
```
PACKET ──► Clara (secretaría) ──► Mason (si no encaja) ──► Feldman
└──► Feldman (si encaja)
```

67
01_ARQUITECTURA/aplicaciones/vision-builder.md Normal file
View File

@@ -0,0 +1,67 @@
# Vision Builder
**Tipo:** Aplicación Web
**Estado:** En desarrollo
---
## Descripción
Sistema de construcción de visiones que se convierten en acciones medibles.
---
## Flujo Principal
```
VISIÓN → MST (Milestones) → ACCIONES + HÁBITOS → BCK (Evidencias)
```
---
## Tipos de Visión
| Tipo | Descripción | Ejemplo |
|------|-------------|---------|
| **fitness** | Transformación física | Perder 10kg en 12 semanas |
| **career** | Desarrollo profesional | Conseguir ascenso |
| **project** | Proyecto específico | Lanzar MVP |
| **habit** | Crear hábito | Meditar diario |
| **learning** | Aprendizaje | Dominar Python |
| **finance** | Finanzas | Ahorrar €10k |
---
## Acciones vs Hábitos
| Concepto | Descripción | Ejemplo |
|----------|-------------|---------|
| **Acción** | Tarea única | Comprar báscula |
| **Hábito** | Comportamiento recurrente | Entrenar 5x/semana |
---
## Tablas
```sql
deck_visiones -- Visiones del usuario
deck_milestones -- MST: objetivos con fecha
deck_acciones -- Tareas únicas
deck_habitos -- Comportamientos recurrentes
deck_habito_registros -- Tracking diario de hábitos
deck_bck -- Bloques de evidencia
```
---
## Integración con HST
Cada visión puede etiquetarse con tags HST:
```json
{
"vision": "Transformación física",
"tags": ["fitness", "health", "body"],
"h_maestro": ["abc...", "def...", "ghi..."]
}
```

89
01_ARQUITECTURA/entidades/corp.md Normal file
View File

@@ -0,0 +1,89 @@
# CORP
**Tipo:** Servidor Empresarial
**IP:** 92.112.181.188
**Dominio:** tzzrcorp.me
**Estado:** Operativo
---
## Descripción
CORP es el **servidor empresarial** del ecosistema. Gestiona múltiples usuarios y mayor complejidad que DECK.
---
## Arquitectura
```
┌──────────────────────────────────────────────────────────────────┐
│ CORP │
│ (Servidor Empresarial) │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ DIRECTUS │ │ NEXTCLOUD │ │ ODOO │ │
│ │ (admin) │ │ (archivos) │ │ (ERP) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Componentes Internos │ │
│ │ Margaret (secretaría) │ Jared (producción) │ │
│ │ Mason (administración) │ Feldman (contable) │ │
│ │ Sentinel (auditoría) │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ PostgreSQL + Redis │ │
│ └───────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## Componentes Internos
| Componente | Puerto | Función |
|------------|--------|---------|
| Margaret (secretaría) | 5051 | Ingesta inmutable, múltiples usuarios |
| Jared (producción) | 5052 | Flujos predefinidos, mayor complejidad |
| Mason (administración) | 5053 | Enriquecimiento |
| Feldman (contable) | 5054 | Consolidación |
| Sentinel (auditoría) | - | Verificación LIGHT/DEEP |
---
## Servicios Docker
| Servicio | Puerto | Estado |
|----------|--------|--------|
| Directus | 8055 | OK |
| Nextcloud | 8080 | OK |
| Vaultwarden | 8081 | OK |
| Shlink | 8082 | OK |
| Odoo | 8069 | OK |
| ntfy | 8880 | OK |
| HSU API | 5002 | OK |
| Redis | 6379 | OK |
| PostgreSQL | 5432 | OK |
| Caddy | 80/443 | OK |
---
## Almacenamiento
- **Bucket R2:** corp
- **Protocolo:** locker://corp/...
---
## Diferencias con DECK
| Aspecto | DECK | CORP |
|---------|------|------|
| Dominio | tzzrdeck.me | tzzrcorp.me |
| Usuarios | Uno | Múltiples |
| Secretaría | Clara | Margaret |
| Producción | Alfred | Jared |
| Complejidad | Menor | Mayor |

254
01_ARQUITECTURA/entidades/deck.md Normal file
View File

@@ -0,0 +1,254 @@
# DECK
**Tipo:** Servidor Personal
**IP:** 72.62.1.113
**Dominio:** tzzrdeck.me
---
## Rol en el Ecosistema
DECK es el **servidor central** y **punto de iniciación** de todas las conexiones hacia los servicios de IA.
```
┌─────────────────────────────────────────────────────────────────┐
│ PRINCIPIO DECK │
│ │
│ "DECK inicia TODAS las conexiones. Los servicios son │
│ stateless. Cada request lleva su contexto completo." │
└─────────────────────────────────────────────────────────────────┘
```
---
## Funciones
| Función | Descripción |
|---------|-------------|
| **Iniciador** | Todas las llamadas a GRACE, PENNY, FACTORY se originan aquí |
| **Gestor contexto** | Envía información de contexto con cada request |
| **Router despliegue** | Decide si usar self-hosted o externos |
| **Almacén credenciales** | Gestiona API keys vía Key Vault |
---
## Arquitectura
```
┌─────────────────────────────────────────────────────────────────┐
│ DECK │
│ (Servidor Central) │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Directus │ │ FileBrowser │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Vaultwarden │ │ Shlink │ │ Addy.io │ │
│ │ (Key Vault) │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ DEPLOYMENT ROUTER │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ GRACE │ │ PENNY │ │ FACTORY │ │ │
│ │ │ Connector │ │ Connector │ │ Connector │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ └─────────┼────────────────┼────────────────┼───────────────┘ │
└────────────┼────────────────┼────────────────┼──────────────────┘
│ │ │
▼ ▼ ▼
┌────────────────────────────────────────────────────┐
│ SERVICIOS DE IA │
├────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ SELF-HOSTED │ │ EXTERNAL │ │
│ │ (RunPod/GPU) │ │ (APIs) │ │
│ ├─────────────────┤ ├─────────────────┤ │
│ │ Faster Whisper │ │ Groq API │ │
│ │ Local LLM │ │ OpenRouter │ │
│ │ Tesseract │ │ OpenAI │ │
│ │ Embeddings │ │ Anthropic │ │
│ └─────────────────┘ └─────────────────┘ │
└────────────────────────────────────────────────────┘
```
---
## Componentes Internos
| Componente | Puerto | Función |
|------------|--------|---------|
| Clara (secretaría) | 5051 | Ingesta inmutable |
| Alfred (producción) | 5052 | Flujos predefinidos |
| Mason (administración) | 5053 | Enriquecimiento |
| Feldman (contable) | 5054 | Consolidación |
---
## Modos de Despliegue
### EXTERNAL
```yaml
grace:
mode: EXTERNAL
external:
providers_allowed: [groq, openrouter, openai, anthropic]
```
- Todas las llamadas a proveedores externos
- Sin infraestructura propia
- Ideal para: inicio rápido, bajo volumen
### SELF_HOSTED
```yaml
grace:
mode: SELF_HOSTED
self_hosted:
endpoint: "https://your-runpod-endpoint.runpod.net"
timeout_ms: 30000
```
- Todas las llamadas a infraestructura propia
- Requiere RunPod/GPU configurado
- Ideal para: privacidad total, alto volumen
### SEMI (Recomendado)
```yaml
grace:
mode: SEMI
tier_preference:
- SELF_HOSTED
- EXTERNAL
self_hosted:
endpoint: "..."
retry_on_failure: true
external:
providers_allowed: [groq, openrouter]
```
- Intenta self-hosted primero
- Fallback automático a external
- Balance privacidad/disponibilidad
---
## Flujo de Request
```
┌──────────┐ ┌──────────┐ ┌───────────────┐ ┌──────────────┐
│ Cliente │────▶│ DECK │────▶│ Deployment │────▶│ Servicio │
│ │ │ │ │ Router │ │ (IA) │
└──────────┘ └────┬─────┘ └───────┬───────┘ └──────────────┘
│ │
│ 1. Recibe request │
│ 2. Lee config/deployment.yaml
│ 3. Obtiene credenciales de Vaultwarden
│ 4. Construye S-CONTRACT request
│ │
│ ┌────────▼────────┐
│ │ mode: SEMI │
│ ├─────────────────┤
│ │ 1. Try SELF_HOSTED
│ │ 2. If fail → EXTERNAL
│ └─────────────────┘
```
---
## Servicios Docker
| Servicio | Puerto | Descripción |
|----------|--------|-------------|
| PostgreSQL | 5432 | Base de datos principal |
| Directus | 8055 | Interface datos |
| FileBrowser | 8081 | Gestión archivos |
| Vaultwarden | 8082 | Key Vault |
| Shlink | 8083 | Acortador URLs |
| Addy.io | 8084 | Alias correo |
| Redis | 6379 | Cache y colas |
---
## Conectores de IA
### GRACE Connector
- Procesa requests de módulos GRACE
- Soporta todos los M-CONTRACTs
- Maneja fallback chain según M-CONTRACT
### PENNY Connector
- Conexión WebSocket para real-time voice
- Sesiones de voz bidireccionales
- Integración con ASR/TTS
### FACTORY Connector
- Jobs de generación iterativa
- Gestión de iteraciones y convergencia
- Tracking de costos
---
## Gestión de Credenciales
Las credenciales se referencian con URIs `kv://`:
| URI | Contenido |
|-----|-----------|
| `kv://deck/credentials/groq` | API key Groq |
| `kv://deck/credentials/openrouter` | API key OpenRouter |
| `kv://deck/credentials/runpod` | API key RunPod |
| `kv://deck/credentials/grace` | Credenciales consolidadas GRACE |
| `kv://deck/credentials/penny` | Credenciales PENNY |
| `kv://deck/credentials/factory` | Credenciales FACTORY |
---
## Integración S-CONTRACT
DECK construye requests siguiendo S-CONTRACT v2.1:
```json
{
"contract_version": "2.1",
"profile": "FULL",
"envelope": {
"trace_id": "uuid-generado-por-deck",
"idempotency_key": "sha256-del-contenido"
},
"routing": {
"module": "ASR_ENGINE"
},
"deployment": {
"mode": "SEMI",
"tier_preference": ["SELF_HOSTED", "EXTERNAL"],
"credentials_ref": "kv://deck/credentials/grace"
},
"payload": {
"type": "audio",
"encoding": "url",
"content": "https://storage.tzzrdeck.me/audio/file.mp3"
}
}
```
---
## Estructura de Directorios
```
deck/
├── config/
│ └── deployment.yaml # Modos de despliegue
├── docker-compose.yml # Servicios
├── docs/
│ ├── ARQUITECTURA.md
│ └── ESPECIFICACION_SERVIDOR.md
├── .env # Variables entorno
└── README.md
```

58
01_ARQUITECTURA/entidades/flg.md Normal file
View File

@@ -0,0 +1,58 @@
# FLG - Flags
**Tipo:** Marcos Jurídicos
**Estado:** Planificado
---
## Descripción
Los FLG representan **marcos jurídicos**, normativas y países. Determinan las reglas aplicables a cada operación.
---
## Uso
| Contexto | Ejemplo |
|----------|---------|
| País | España, México, Argentina |
| Normativa | RGPD, SOX, ISO 27001 |
| Jurisdicción | UE, LATAM, USA |
---
## Grupos HST Relacionados
Actualmente existe un grupo `flg` en HST con 65 tags de países, pero no como entidad independiente con schema propio.
---
## Schema Propuesto
```sql
CREATE TABLE flags (
id BIGSERIAL PRIMARY KEY,
h_flag VARCHAR(64) UNIQUE NOT NULL,
tipo VARCHAR(50) NOT NULL,
codigo VARCHAR(10),
nombre VARCHAR(255) NOT NULL,
normativas JSONB,
metadata JSONB,
activo BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## Aplicación en Bloques
Cada bloque puede tener un FLG asociado:
```json
{
"h_bloque": "abc123...",
"h_flag": "esp...",
"implicacion": "RGPD aplica, retención 5 años"
}
```

95
01_ARQUITECTURA/entidades/hst.md Normal file
View File

@@ -0,0 +1,95 @@
# HST - Hash Semantic Tagging
**Tipo:** Sistema de Etiquetado
**Estado:** Implementado
---
## Descripción
Sistema de etiquetas semánticas visuales de 3 caracteres. Cada tag tiene un hash SHA-256 único (h_maestro) y una imagen asociada.
---
## 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 |
**Total:** 954 tags maestros
---
## 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"
}
```
---
## Extensiones de Usuario
Los usuarios pueden crear sus propios tags:
| Tabla | Descripción |
|-------|-------------|
| **hsu** | HST Usuario |
| **spu** | SPE Usuario |
| **vsu** | VSN Usuario |
| **vuu** | VUE Usuario |
| **pju** | Proyectos Usuario |
| **flu** | FLG Usuario |
---
## API
**Base URL:** https://tzrtech.org/api
| Endpoint | Método | Descripción |
|----------|--------|-------------|
| /tags | GET | Lista todos los tags |
| /tags/{ref} | GET | Obtiene tag por ref |
| /tags/search | GET | Busca tags |
| /biblioteca | GET | Tags de usuario |

84
01_ARQUITECTURA/entidades/itm.md Normal file
View File

@@ -0,0 +1,84 @@
# ITM - Items
**Tipo:** Entidad de Plano Ideal
**Estado:** Planificado
---
## Descripción
Los ITM representan el **plano ideal** (T0). Son la "partitura" que guía las acciones. Definiciones perfectas de lo que debería existir o lograrse.
---
## Concepto
| Aspecto | Descripción |
|---------|-------------|
| **Naturaleza** | Ideal, abstracta |
| **Temporalidad** | T-N → T-1 → T0 |
| **Energía** | No consume (es definición) |
| **Mutabilidad** | Versionable |
---
## Tipos de Items
| Tipo | Descripción |
|------|-------------|
| **accion_ideal** | Acción que debería ejecutarse |
| **objetivo** | Meta a alcanzar |
| **requerimiento** | Requisito a cumplir |
---
## 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)
);
```
---
## Fórmula Hash
```
h_item = SHA-256(h_instancia:secuencia:tipo:contenido)
```
---
## Relación con Otros Planos
```
ITM (ideal)
│
├──► h_maestro (HST tags)
├──► h_player (PLY responsable)
├──► h_loc (LOC ubicación)
└──► h_flag (FLG normativa)
│
▼ materializa
MST (milestone)
│
▼ genera
BCK (bloque)
```

67
01_ARQUITECTURA/entidades/loc.md Normal file
View File

@@ -0,0 +1,67 @@
# LOC - Locations
**Tipo:** Ubicaciones Geográficas
**Estado:** Planificado
---
## Descripción
Los LOC representan **ubicaciones geográficas** con precisión variable.
---
## Tipos
| Tipo | Descripción |
|------|-------------|
| **punto** | Coordenadas exactas |
| **area** | Zona delimitada |
| **ruta** | Trayecto entre puntos |
---
## 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),
metadata JSONB,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## Fórmula Hash
```
h_loc = SHA-256(lat:lon:precision)
```
---
## Uso en el Sistema
Cada bloque puede tener una ubicación asociada:
```json
{
"h_bloque": "abc123...",
"h_loc": "geo456...",
"lat": 41.6488,
"lon": -0.8891,
"precision_metros": 10
}
```
Esto permite:
- Geolocalización de evidencias
- Verificación de ubicación
- Análisis espacial de operaciones

64
01_ARQUITECTURA/entidades/ply.md Normal file
View File

@@ -0,0 +1,64 @@
# PLY - Players
**Tipo:** Entidad de Identidad
**Estado:** Planificado
---
## Descripción
Los PLY representan la **identidad de actores** en el sistema: personas, empresas, agentes.
---
## Tipos
| Tipo | Descripción |
|------|-------------|
| **persona** | Usuario individual |
| **empresa** | Organización |
| **agente** | Sistema automatizado |
---
## Schema Propuesto
```sql
CREATE TABLE players (
id BIGSERIAL PRIMARY KEY,
h_player VARCHAR(64) UNIQUE NOT NULL,
tipo VARCHAR(50) NOT NULL,
nombre VARCHAR(255) NOT NULL,
email VARCHAR(255),
metadata JSONB,
activo BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## Fórmula Hash
```
h_player = SHA-256(tipo:identificador_unico)
```
---
## Uso en el Sistema
Cada acción registrada incluye referencia al player:
```json
{
"h_bloque": "abc123...",
"h_player": "def456...",
"accion": "completó tarea X"
}
```
Esto permite:
- Trazabilidad de quién hizo qué
- Portfolio verificable por persona
- Auditoría sin ambigüedad

338
01_ARQUITECTURA/overview.md
View File

@@ -1,167 +1,221 @@
# Arquitectura Overview
# Overview
**Versión:** 5.0
**Fecha:** 2024-12-24
**Versión:** 1.1
**Estado:** Definición
---
## Principio Fundamental
## Visión General
> **ARCHITECT es el constructor. DECK y CORP son instancias autónomas.**
- **ARCHITECT**: Construye, despliega, coordina. NO es dependencia runtime.
- **DECK/CORP**: Operan independientemente. Funcionan si ARCHITECT está caído.
Sistema de arquitecturas personales y empresariales. ARCHITECT (con Claude) construye y despliega servidores autónomos (DECK, CORP) que operan independientemente. Los componentes internos son microservicios backend, no IA. Las instancias están diseñadas para **consumir** servicios de IA externos (APIs, RunPod), no para contenerla.
---
## Diagrama General
## Arquitectura General
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA DE CONSTRUCCIÓN (solo deploy/dev) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ARCHITECT (69.62.126.110) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐ │ │
│ │ │PostgreSQL│ │ Gitea │ │Orchestrator│ │ Infisical │ │ │
│ │ │ contexto │ │ 25 repos │ │ v5 │ │ (master) │ │ │
│ │ └──────────┘ └──────────┘ └────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ Rol: Construcción, deployment, gestión central de secretos │
│ NO es dependencia runtime de las instancias │
└─────────────────────────────────────────────────────────────────────────┘
│ │ │
deploy │ │ │ deploy
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CAPA DE INSTANCIAS (autónomas) │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │
│ │ DECK │ │ CORP │ │ HST │ │
│ │ 72.62.1.113 │ │ 92.112.181.188 │ │ 72.62.2.84 │ │
│ │ │ │ │ │ │ │
│ │ secretaria :5051 │ │ secretaria :5051 │ │ 973 tags │ │
│ │ producción :5052 │ │ producción :5052 │ │ API pública │ │
│ │ admin.vo :5053 │ │ admin.vo :5053 │ │ Directus :8055 │ │
│ │ contable :5054 │ │ contable :5054 │ │ │ │
│ │ │ │ │ │ │ │
│ │ Vaultwarden │ │ 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│ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ ARCHITECT │
│ PostgreSQL central │ Gitea │ Orchestrator │ Infisical │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ DECK │ │ CORP │ │ HST │
│ │ │ │ │ │
│ secretaría │ │ secretaría │ │ 973 tags │
│ administración │ │ administración │ │ API pública │
│ contable │ │ contable │ │ │
│ producción │ │ producción │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
└────────┬───────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare R2 (buckets) │
│ architect │ deck │ corp │ hst │ locker │
└─────────────────────────────────────────────────────────────┘
```
---
## Flujo de Datos
## Flujo de Datos Principal
El sistema tiene dos flujos según el origen y completitud de la información:
### Diagrama General
```
PACKET (App móvil)
│
│ POST /ingest
│ Content-Type: multipart/form-data
│ X-Auth-Key: {h_instancia}
│
▼
┌─────────────────────────────────────────┐
│ secretaria (CLARA / MARGARET) │
│ │
│ 1. Validar h_instancia │
│ 2. Calcular h_entrada (SHA-256) │
│ 3. Subir archivos a R2 │
│ 4. Insertar en log │
│ 5. Estado: 'recibido' (inmutable) │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ producción (ALFRED / JARED) │
│ │
│ 1. Definir orden de ejecución │
│ 2. Aplicar flujos predefinidos │
│ 3. Enviar a administrativo │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ administrativo (MASON) │
│ │
│ 1. Recibir de producción │
│ 2. Ventana flotante 24h │
│ 3. Usuario enriquece datos │
│ 4. [Futuro] GRACE extrae información │
│ 5. Enviar a contable cuando listo │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ contable (FELDMAN) │
│ │
│ 1. Recibir en 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 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ auditoría (SENTINEL) [planificado] │
│ │
│ LIGHT: Cada 5 min, reglas automáticas │
│ DEEP: Cada 1 hora, muestreo con LLM │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ ORÍGENES │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ PRODUCCIÓN │ │ ENTRADA MANUAL │ │
│ │ Alfred/Jared │ │ (Packet, API, manual) │ │
│ │ │ │ │ │
│ │ Flujos │ │ Datos incompletos │ │
│ │ predefinidos │ │ o ad-hoc │ │
│ └────────┬────────┘ └────────────┬────────────┘ │
│ │ │ │
│ │ (datos completos) │ │
│ │ │ │
└───────────┼─────────────────────────────────┼──────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ SECRETARÍA │
│ Clara / Margaret │
├─────────────────────────────────────────────────────────────┤
│ • Punto de entrada ÚNICO │
│ • Log inmutable │
│ • Todo se registra exactamente como llega │
└─────────────────────────────────────────────────────────────┘
│
│
┌────────┴────────┐
│ │
encaja no encaja
│ │
│ ▼
│ ┌─────────────────────────────────────────────────────┐
│ │ ADMINISTRACIÓN │
│ │ Mason │
│ ├─────────────────────────────────────────────────────┤
│ │ • Ventana de enriquecimiento (24h configurable) │
│ │ • Usuario completa/corrige datos │
│ │ • Auto-envío si expira el tiempo │
│ └──────────────────────────┬──────────────────────────┘
│ │
└───────────────┬───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CONTABLE │
│ Feldman │
├─────────────────────────────────────────────────────────────┤
│ • Cola de validación (24h configurable) │
│ • Consolidación en bloques inmutables │
│ • Encadenamiento hash (blockchain-style) │
└─────────────────────────────────────────────────────────────┘
```
### Regla de Decisión
| Condición | Ruta | Descripción |
|-----------|------|-------------|
| **Encaja** | Secretaría → Feldman | Datos completos de flujo predefinido |
| **No encaja** | Secretaría → Mason → Feldman | Entrada manual o incompleta |
### Flujo de Producción (encaja)
Cuando la información viene de un proceso predefinido y está completa:
```
Producción (Alfred/Jared)
│
│ flujo predefinido completo
▼
Secretaría (Clara/Margaret) ← Registro inmutable
│
│ directo (salta Mason)
▼
Contable (Feldman) ← Consolidación
```
### Flujo Estándar (no encaja)
Cuando la información es manual, ad-hoc o incompleta:
```
Entrada manual (Packet, API, etc.)
│
▼
Secretaría (Clara/Margaret) ← Registro inmutable
│
▼
Administración (Mason) ← Enriquecimiento (24h)
│
▼
Contable (Feldman) ← Consolidación
```
---
## Comunicación Entre Servidores
## Auditoría (Sentinel)
| 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 |
Sentinel es un **componente independiente** que opera de forma transversal sobre el sistema:
```
┌─────────────────────────────────────────────────────────────┐
│ SENTINEL │
│ (Auditoría) │
├─────────────────────────────────────────────────────────────┤
│ │
│ Monitoriza y verifica integridad en múltiples puntos: │
│ │
│ • Secretaría ←── verifica inmutabilidad del log │
│ • Mason ←── verifica ventanas temporales │
│ • Feldman ←── verifica encadenamiento de bloques │
│ │
│ Modos de operación: │
│ • LIGHT: verificación rápida (cada 5 min) │
│ • DEEP: auditoría completa (cada 1h) │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Bases de Datos
## Principio de Diseño
| 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 |
### Constructores, no gestores
ARCHITECT (con Claude) es un **constructor de arquitecturas**, no un gestor permanente.
- ARCHITECT diseña y construye la arquitectura de cada servidor
- Cuando la arquitectura esté madura, el servidor será **clonable e independiente**
- DECK y CORP funcionan sin conexión a ARCHITECT ni a Claude
- Son sistemas diseñados para **usar** servicios de IA (APIs externas, RunPod), no para contenerla
### Descentralización operativa
```
Architect App (centralizado) → Diseña moldes
↓
Instancias reales (descentralizadas)
↓
Cada una con su CORP, su DECK, sus agentes
```
---
## Modelo de Instancias
**DECK** y **CORP** son plantillas. En producción habrá múltiples instancias:
| Tipo | Ejemplos |
|------|----------|
| **DECK** | "Deck de Juan", "Deck de Victoria" |
| **CORP** | "Empresa A SL", "Empresa B Corp" |
Cada instancia:
- Tiene su propio bucket de almacenamiento
- Puede renombrar sus agentes
- **Opera de forma autónoma** (no depende de ARCHITECT en runtime)
- Tiene su propio gestor de secretos
- Hace sus propios backups a R2
---
## Servicios Compartidos (Opcionales)
Las instancias **pueden** conectarse a servicios GPU compartidos:
| Servicio | Función | Requerido |
|----------|---------|-----------|
| Grace | Extracción IA | Opcional |
| The Factory | Generación | Opcional |
| Circle | Colaboración | Opcional |
> **Nota:** Si los servicios compartidos no están disponibles, la instancia sigue operando. Solo las funciones de IA estarán limitadas.

230
01_ARQUITECTURA/servidores.md
View File

@@ -1,230 +0,0 @@
# 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 | - |