tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
25eee88c15c3377f7f688626e7f1ebba25b7b0b0
system-docs/07_INTERFACES/07_INTERFACES.md
ARCHITECT 36f87ca9b7 Add 07_INTERFACES - Documentación de interfaces desplegadas 
Incluye:
- Interfaces web (MindLink, Flow-UI, Directus)
- APIs microservicios TZZR (Clara, Alfred, Mason, Feldman)
- HST API
- Tablas PostgreSQL por servidor
- Resumen de puertos y repositorios
- Comandos de gestión

Basado en auditoría real del 2025-12-31

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-31 19:28:36 +00:00

19 KiB
Raw Blame History

07_INTERFACES

Versión: 1.0
Estado: Documentación basada en despliegue real
Fecha: 2025-12-31

Resumen

Este documento describe las interfaces desplegadas y operativas en el ecosistema TZZR.

Tipo Cantidad Servidores
Interfaces Web 6 DECK, CORP, HST, ARCHITECT
APIs Microservicios TZZR 8 DECK (4), CORP (4)
APIs Externas 1 HST

§1. INTERFACES WEB

1.1 MindLink - Portal Unificado

Portal visual que centraliza acceso a todos los servicios TZZR con estado en tiempo real.

Instancias Desplegadas

Instancia URL Servidor Puerto
CENTRAL https://link.tzzrarchitect.me DECK (72.62.1.113) 5090
CORP https://link.tzzrcorp.me CORP (92.112.181.188) 5090
DECK https://link.tzzrdeck.me DECK (72.62.1.113) 5090

Stack Técnico

Componente Tecnología
Backend Python + Flask
Frontend Jinja2 + Vanilla JS
Proceso systemd
Ubicación /opt/mindlink/

API Endpoints

GET  /                        # Frontend
GET  /api/health              # Health check
GET  /api/services            # Lista servicios por categoría
GET  /api/services/status     # Estado de todos los servicios
GET  /api/service/<id>/status # Estado de un servicio

# URL Shortener integrado
POST /api/shorten             # Acortar URL
GET  /api/urls                # Listar URLs
GET  /s/<code>                # Redirección
GET  /api/url/<code>/stats    # Estadísticas

Gestión

# Estado
systemctl status mindlink

# Reiniciar
systemctl restart mindlink

# Logs
journalctl -u mindlink -f

1.2 Flow-UI - Gestión de Flujos

Interfaz web para gestionar el flujo de datos del sistema TZZR.

ENTRADA (Clara/Margaret) → MASON (Enriquecimiento) → FELDMAN (Registro + Merkle)

Instancias Desplegadas

Instancia URL Servidor Puerto
DECK https://flows.tzzrdeck.me DECK (72.62.1.113) 5080
CORP https://flows.tzzrcorp.me CORP (92.112.181.188) 5080

Stack Técnico

Componente Tecnología
Backend Python + Flask
Frontend Jinja2 + Vanilla JS
Proceso systemd
Ubicación /opt/flow-ui/

Secciones del Frontend

Sección Función
Entrada Formulario de ingesta y lista de entradas
Mason Editor de items pendientes de enriquecimiento
Feldman Milestones, bloques y verificación de hashes
Flujos Gestión de flujos automatizados (Alfred/Jared)
HSU Tags y grupos HSU
Dashboard Vista general y estadísticas
Admin Logs y restart de servicios

API Endpoints

# Core
POST /api/ingest                    # Enviar datos a Clara/Margaret
GET  /api/entradas                  # Listar entradas
GET  /api/stats                     # Estadísticas

# Mason
GET  /api/mason/pending             # Items pendientes
GET  /api/mason/item/<id>           # Detalle item
PUT  /api/mason/item/<id>           # Actualizar item
POST /api/mason/item/<id>/resolve   # Resolver → Feldman
POST /api/mason/item/<id>/descartar # Descartar

# Feldman
GET  /api/feldman/milestones        # Listar milestones
GET  /api/feldman/blocks            # Listar bloques
GET  /api/feldman/verify/<hash>     # Verificar hash

# Flujos
GET  /api/flujos                    # Listar flujos
POST /api/flujos                    # Crear flujo
POST /api/flujos/<id>/ejecutar      # Ejecutar flujo
GET  /api/ejecuciones               # Historial

# Admin
GET  /api/admin/servicios           # Estado servicios
GET  /api/admin/logs/<svc>          # Logs
POST /api/admin/restart/<svc>       # Reiniciar

Gestión

systemctl status flow-ui
systemctl restart flow-ui
journalctl -u flow-ui -f

1.3 Directus - CMS Headless

Interfaz de administración de datos y API REST/GraphQL automática.

Instancias Desplegadas

Instancia URL Servidor Puerto Base de Datos
DECK https://directus.tzzrdeck.me DECK 8055 deck
CORP https://directus.tzzrcorp.me CORP 8055 corp
HST https://hst.tzrtech.org HST 8055 hst_images
Lumalia - HST 8056 lumalia
Personal - HST 8057 personal
ARCHITECT https://directus.tzzrarchitect.me ARCHITECT 8055 tzzr

Proceso

Todas las instancias corren como contenedores Docker.

1.4 Servicios Auxiliares

DECK (72.62.1.113)

Servicio Puerto URL Descripción
Nextcloud 8084 nextcloud.tzzrdeck.me Almacenamiento
Vaultwarden 8085 vault.tzzrdeck.me Contraseñas
Shlink 8083 - URLs cortas
NTFY 8080 - Notificaciones
Odoo 8069 - ERP
Windmill 8100 - Workflows
Mailcow 8443 - Email
FileBrowser 8082 - Archivos

CORP (92.112.181.188)

Servicio Puerto URL Descripción
Nextcloud 8080 nextcloud.tzzrcorp.me Almacenamiento
Vaultwarden 8081 vault.tzzrcorp.me Contraseñas
Shlink 8082 shlink.tzzrcorp.me URLs cortas
Addy 8083 addy.tzzrcorp.me Email aliases
NTFY 8880 ntfy.tzzrcorp.me Notificaciones
Odoo 8069 erp.tzzrcorp.me ERP
Windmill 8000 localhost:8000 Workflows

HST (72.62.2.84)

Servicio Puerto Descripción
FileBrowser 8081 Administrador archivos
HST-Images 80/443 Nginx imágenes estáticas

ARCHITECT (69.62.126.110)

Servicio Puerto URL Descripción
Gitea 3000 git.tzzrarchitect.me Repositorios
Windmill 8100 - Workflows
Infisical 8082 - Secretos

§2. APIs MICROSERVICIOS TZZR

2.1 Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                          DECK                                   │
│                      (72.62.1.113)                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐        │
│  │  Clara  │ → │  Mason  │ → │ Feldman │   │  Alfred │        │
│  │  :5051  │   │  :5053  │   │  :5054  │   │  :5052  │        │
│  └─────────┘   └─────────┘   └─────────┘   └─────────┘        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          CORP                                   │
│                     (92.112.181.188)                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐        │
│  │Margaret │ → │  Mason  │ → │ Feldman │   │  Jared  │        │
│  │  :5051  │   │  :5053  │   │  :5054  │   │  :5052  │        │
│  └─────────┘   └─────────┘   └─────────┘   └─────────┘        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2.2 Clara (DECK) / Margaret (CORP)

Función: Secretaría - Punto de entrada inmutable del sistema.

Aspecto Valor
Puerto 5051
Versión 1.0.0
Contenedor clara-service / margaret-service

Endpoints

GET  /health                  # Health check
POST /api/v1/ingest           # Registrar entrada
GET  /api/v1/entries          # Listar entradas
GET  /api/v1/entry/<id>       # Detalle entrada

Request de Ingesta

POST /api/v1/ingest
{
  "contenido": "texto o datos",
  "origen": "manual|api|flujo",
  "metadata": {
    "usuario": "id",
    "timestamp": "ISO8601"
  }
}

Response

{
  "id": "uuid",
  "hash": "sha256",
  "timestamp": "ISO8601",
  "status": "registrado"
}

2.3 Alfred (DECK) / Jared (CORP)

Función: Producción - Flujos predefinidos y automatización.

Aspecto Valor
Puerto 5052
Versión 1.0.0
Contenedor alfred-service / jared-service

Endpoints

GET  /health                      # Health check
GET  /api/v1/flujos               # Listar flujos definidos
POST /api/v1/flujos               # Crear flujo
GET  /api/v1/flujo/<id>           # Detalle flujo
POST /api/v1/flujo/<id>/ejecutar  # Ejecutar flujo
GET  /api/v1/ejecuciones          # Historial ejecuciones

Estructura de Flujo

{
  "id": "uuid",
  "nombre": "Proceso mensual",
  "pasos": [
    {"orden": 1, "accion": "ingest", "config": {}},
    {"orden": 2, "accion": "enrich", "config": {}},
    {"orden": 3, "accion": "validate", "config": {}}
  ],
  "trigger": "manual|cron|evento",
  "activo": true
}

2.4 Mason

Función: Administración - Enriquecimiento de datos.

Aspecto Valor
Puerto 5053
Versión 1.0.0
Contenedor mason-service
Igual en DECK y CORP

Endpoints

GET  /health                      # Health check
GET  /api/v1/pending              # Items pendientes
GET  /api/v1/item/<id>            # Detalle item
PUT  /api/v1/item/<id>            # Actualizar item
POST /api/v1/item/<id>/resolve    # Enviar a Feldman
POST /api/v1/item/<id>/discard    # Descartar
GET  /api/v1/stats                # Estadísticas

Estados de un Item

Estado Descripción
pending Esperando enriquecimiento
in_progress Siendo editado
resolved Enviado a Feldman
discarded Descartado

2.5 Feldman

Función: Contabilidad - Registro final inmutable con verificación Merkle.

Aspecto Valor
Puerto 5054
Versión 3.0-unified
Contenedor feldman-service
Igual en DECK y CORP

Endpoints

GET  /health                      # Health check
GET  /api/v1/milestones           # Listar milestones
GET  /api/v1/blocks               # Listar bloques
GET  /api/v1/block/<id>           # Detalle bloque
POST /api/v1/consolidate          # Consolidar cola → bloque
GET  /api/v1/verify/<hash>        # Verificar integridad
GET  /api/v1/merkle/<batch_id>    # Obtener prueba Merkle
GET  /api/v1/stats                # Estadísticas

Estructura de Bloque

{
  "id": "uuid",
  "numero": 42,
  "hash": "sha256",
  "registros": ["hash1", "hash2", "hash3"],
  "merkle_root": "sha256",
  "timestamp": "ISO8601",
  "anterior": "hash_bloque_41"
}

Verificación de Integridad

GET /api/v1/verify/abc123def456...

Response:
{
  "hash": "abc123def456...",
  "existe": true,
  "bloque": 42,
  "merkle_proof": ["hash1", "hash2"],
  "verificado": true
}

§3. HST API

Base URL: https://tzrtech.org/api
Puerto: 5001
Servidor: HST (72.62.2.84)

3.1 Descripción

API REST para acceder al sistema de tags semánticos (Hash Semantic Tagging).

3.2 Endpoints Públicos

Listar Tags

GET /tags

Query params:

Param Tipo Descripción
grupo string Filtrar por grupo (hst, spe, vsn, flg, vue)
activo boolean Solo activos
limit integer Límite de resultados

Response:

{
  "tags": [
    {
      "ref": "person",
      "h_maestro": "a1b2c3...",
      "grupo": "hst",
      "nombre_es": "Persona",
      "nombre_en": "Person",
      "imagen_url": "https://tzrtech.org/a1b2c3...png"
    }
  ],
  "total": 639
}

Obtener Tag

GET /tags/{ref}

Response:

{
  "ref": "person",
  "h_maestro": "a1b2c3...",
  "grupo": "hst",
  "nombre_es": "Persona",
  "nombre_en": "Person",
  "descripcion": "...",
  "imagen_url": "https://tzrtech.org/a1b2c3...png",
  "activo": true,
  "version": 1
}

Buscar Tags

GET /tags/search?q={query}

Response:

{
  "query": "person",
  "results": [
    { "ref": "person", "score": 1.0 },
    { "ref": "people", "score": 0.8 }
  ]
}

3.3 Endpoints Autenticados

Biblioteca de Usuario

GET /biblioteca
Authorization: Bearer {token}

Response:

{
  "user_id": 123,
  "tags": [
    {
      "ref": "mi_tag",
      "h_usuario": "def456...",
      "nombre": "Mi Tag Personal"
    }
  ]
}

Crear Tag de Usuario

POST /biblioteca
Authorization: Bearer {token}
Content-Type: application/json

{
  "ref": "mi_tag",
  "nombre": "Mi Tag Personal",
  "metadata": {}
}

3.4 Grupos de Tags

Grupo Cantidad Descripción
hst 639 Tags del sistema
spe 145 Especializaciones
vsn 84 Visiones
flg 65 Flags/Marcos jurídicos
vue 21 Vistas

3.5 Rate Limits

Tipo Límite
Público 100 req/min
Autenticado 1000 req/min

§4. TABLAS POSTGRESQL

4.1 Resumen por Servidor

Servidor Bases de Datos Total Tablas
DECK tzzr, deck 30
CORP tzzr, corp 89
HST directus, hst_images, lumalia, personal 143
ARCHITECT tzzr, windmill 122

4.2 Tablas Core TZZR

Secretaría (Clara/Margaret)

Tabla Servidor Descripción
immutable_log DECK, CORP Log inmutable principal
clara_log DECK Log específico Clara
clara_registros DECK Registros Clara
margaret_log CORP Log específico Margaret
margaret_registros CORP Registros Margaret

Administración (Mason)

Tabla Servidor Descripción
incidencias DECK, CORP Items pendientes de resolver

Contabilidad (Feldman)

Tabla Servidor Descripción
feldman_cola DECK, CORP Cola de validación
feldman_validaciones CORP Registro de validaciones
bloques DECK, CORP Bloques consolidados
completados DECK, CORP Registros finalizados
milestones DECK, CORP Hitos del sistema
merkle_batches DECK, CORP Lotes Merkle

Producción (Alfred/Jared)

Tabla Servidor Descripción
flujos_predefinidos DECK, CORP Definiciones de flujos
flujo_ejecuciones DECK, CORP Historial de ejecuciones

Extensiones Usuario (HSU)

Tabla Servidor Descripción
hsu DECK, CORP Tags de usuario
pju DECK, CORP Proyectos usuario
spu DECK, CORP Especializaciones usuario
vsu DECK, CORP Visiones usuario
vuu DECK, CORP Vistas usuario
flu DECK, CORP Flags usuario

Sincronización

Tabla Servidor Descripción
hst_mirror DECK, CORP Espejo de tags HST

4.3 Tablas HST

Tabla Base de Datos Descripción
hst hst_images, lumalia, personal Tags principales
flg hst_images, lumalia, personal Flags/marcos jurídicos
spe hst_images Especializaciones
vsn hst_images Visiones
vue hst_images Vistas
graph_edges hst_images Relaciones entre tags
tag_categorias hst_images Categorías
itm lumalia, personal Items (plano ideal)
loc lumalia, personal Ubicaciones
ply lumalia, personal Players (actores)

§5. RESUMEN DE PUERTOS

Puerto Servicio DECK CORP HST ARCHITECT
80/443 Reverse Proxy Caddy Caddy Docker Nginx
3000 Gitea - - - ✓
5001 HST-API - - ✓ -
5051 Clara/Margaret ✓ ✓ - -
5052 Alfred/Jared ✓ ✓ - -
5053 Mason ✓ ✓ - -
5054 Feldman ✓ ✓ - -
5080 Flow-UI ✓ ✓ - -
5090 MindLink ✓ ✓ - -
8055 Directus ✓ ✓ ✓ ✓
8080/8880 NTFY/Nextcloud NTFY NC - -
8100 Windmill ✓ - - ✓

§6. REPOSITORIOS

Gitea: https://git.tzzrarchitect.me

Organización tzzr (29 repos)

Microservicios

Repo Descripción Lenguaje
clara Entrada DECK Python
margaret Entrada CORP Python
alfred Asistente DECK Python
jared Flujos CORP Python
mason Enriquecimiento Python
feldman Validador + Merkle Python
sentinel Auditoría Python

Interfaces

Repo Descripción
flow-ui Interfaz de flujos
mindlink Portal unificado
packet App móvil (Dart)

Sistema

Repo Descripción
captain-claude Sistema multiagente
orchestrator Orquestación v5
system-docs Documentación
system-plan Plan de implementación
contratos-comunes Contratos compartidos

GPU Services (No desplegados)

Repo Descripción Estado
grace Módulos IA Repo existe, no desplegado
penny Asistente voz Repo existe, no desplegado
the-factory Generación iterativa Repo existe, no desplegado

Apéndice: Comandos de Gestión

Servicios systemd

# MindLink
systemctl status|start|stop|restart mindlink
journalctl -u mindlink -f

# Flow-UI
systemctl status|start|stop|restart flow-ui
journalctl -u flow-ui -f

Contenedores Docker

# Ver estado
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Logs de microservicio
docker logs -f clara-service
docker logs -f feldman-service

# Reiniciar
docker restart jared-service mason-service feldman-service

# Health check manual
curl http://localhost:5051/health
curl http://localhost:5052/health
curl http://localhost:5053/health
curl http://localhost:5054/health

PostgreSQL

# Listar bases de datos
sudo -u postgres psql -c "\l"

# Ver tablas
sudo -u postgres psql -d tzzr -c "\dt"

# Query específica
sudo -u postgres psql -d tzzr -c "SELECT count(*) FROM immutable_log;"

Documento generado a partir del estado real de despliegue
Fecha: 2025-12-31

Reference in New Issue View Git Blame Copy Permalink