system-docs/99_ANEXOS/ANEXO_1_REFERENCIA_TECNICA.md

ANEXO 1 - REFERENCIA TÉCNICA

Versión: 10.0
Fecha: 6 Enero 2026
Sistema: TZZR

---

§1. INTERFACES WEB DESPLEGADAS

1.1 MindLink - Portal Unificado

Portal visual que centraliza acceso a todos los servicios TZZR.

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

Stack: Python + Flask + Jinja2
Ubicación: /opt/mindlink/
Proceso: systemd

Endpoints

GET  /                        # Frontend
GET  /api/health              # Health check
GET  /api/services            # Lista servicios
GET  /api/services/status     # Estado servicios
POST /api/shorten             # Acortar URL
GET  /s/<code>                # Redirección

---

1.2 Flow-UI - Gestión de Flujos

Interfaz web para gestionar el flujo de datos TZZR.

Instancia	URL	Servidor	Puerto
DECK	https://flows.tzzrdeck.me	DECK	5080
CORP	https://flows.tzzrcorp.me	CORP	5080

Stack: Python + Flask + Jinja2
Ubicación: /opt/flow-ui/
Proceso: systemd

Secciones

Sección	Función
Entrada	Formulario ingesta, lista entradas
Mason	Editor items pendientes
Feldman	Milestones, bloques, verificación
Flujos	Gestión flujos (Alfred/Jared)
HST	Tags y grupos
Dashboard	Vista general
Admin	Logs y restart

Endpoints

POST /api/ingest                    # Enviar a Clara/Margaret
GET  /api/entradas                  # Listar entradas
GET  /api/mason/pending             # Items pendientes
PUT  /api/mason/item/<id>           # Actualizar item
POST /api/mason/item/<id>/resolve   # Resolver → Feldman
GET  /api/feldman/milestones        # Listar milestones
GET  /api/feldman/verify/<hash>     # Verificar hash
GET  /api/flujos                    # Listar flujos
POST /api/flujos/<id>/ejecutar      # Ejecutar flujo

---

1.3 Directus - CMS Headless

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

---

§2. SERVICIOS AUXILIARES

2.1 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
Windmill	8100	-	Workflows
Mailcow	8443	-	Email
FileBrowser	8082	-	Archivos

2.2 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
Windmill	8000	localhost:8000	Workflows

2.3 HST (72.62.2.84)

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

2.4 ARCHITECT (69.62.126.110)

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

---

§3. RESUMEN DE PUERTOS

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

---

§4. SERVIDOR HST

4.1 Estructura Filesystem

/opt/hst/
├── api/                     # Flask API (app.py, Dockerfile)
├── images/                  # Imágenes PNG (926 archivos)
│   └── thumb/               # Thumbnails
├── directus/
│   ├── extensions/
│   └── uploads/
├── nginx/
│   └── default.conf
├── scripts/
│   └── refresh_views.sh
├── filebrowser/
├── backups/
└── docker-compose.yml

4.2 Contenedores Docker HST

Contenedor	Puerto	Función
hst-api	5000	API Flask principal
hst-images	80, 443	Nginx servidor imágenes
directus_hst	8055	CMS Directus
directus_lumalia	8056	CMS Lumalia
directus_personal	8057	CMS Personal
postgres_hst	5432	PostgreSQL
filebrowser	8081	Gestión archivos

4.3 Dominios HST

Dominio	Destino
tzrtech.org	Imágenes estáticas + /api/
hst.tzrtech.org	Directus CMS
graph.tzrtech.org	API directa
lumalia.tzrtech.org	Directus Lumalia
pablo.tzrtech.org	Directus Personal

4.4 API HST

Base: https://tzrtech.org/api/

Endpoint	Método	Descripción
/api/index.json	GET	Índice general
/api/tags	GET	Buscar tags
/api/tags/{mrf}	GET	Obtener tag por hash
/api/tags/{mrf}/children	GET	Hijos de un tag
/api/tags/{mrf}/related	GET	Tags relacionados
/api/tree	GET	Árbol jerárquico
/api/graph	GET	Grafo de relaciones
/api/library	GET	Lista de bibliotecas
/api/grupos	GET	Lista de grupos

---

§5. TABLAS POSTGRESQL POR SERVIDOR

5.1 Resumen

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

5.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

Contabilidad (Feldman)

Tabla	Servidor	Descripción
feldman_cola	DECK, CORP	Cola de validación
feldman_validaciones	CORP	Registro 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 ejecuciones

Extensiones Usuario

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
hst_mirror	DECK, CORP	Espejo de tags HST

5.3 Tablas HST

Tabla	Base de Datos	Descripción
hst	hst_images, lumalia, personal	Tags principales
flg	hst_images, lumalia, personal	Flags
spe	hst_images	Especificaciones
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
loc	lumalia, personal	Ubicaciones
ply	lumalia, personal	Players

---

§6. REPOSITORIOS GITEA

URL: https://git.tzzrarchitect.me
Organización: tzzr (29 repos)

6.1 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

6.2 Interfaces

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

6.3 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

6.4 GPU Services (No desplegados)

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

---

§7. COMANDOS DE GESTIÓN

7.1 Servicios systemd

# MindLink
systemctl status mindlink
systemctl restart mindlink
journalctl -u mindlink -f

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

7.2 Contenedores Docker

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

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

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

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

7.3 PostgreSQL

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

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

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

7.4 HST Específico

# SSH
ssh -i ~/.ssh/tzzr root@72.62.2.84

# PostgreSQL HST
docker exec -it postgres_hst psql -U directus -d hst_images

# Regenerar vistas materializadas
/opt/hst/scripts/refresh_views.sh

# Docker Compose HST
cd /opt/hst
docker compose up -d
docker compose down
docker compose logs -f

---

§8. OPENAPI SPEC (Resumen)

8.1 Servidores

Servicio	URL DECK	URL CORP
Clara/Margaret	http://72.62.1.113:5051	http://92.112.181.188:5051
Alfred/Jared	http://72.62.1.113:5052	http://92.112.181.188:5052
Mason	http://72.62.1.113:5053	http://92.112.181.188:5053
Feldman	http://72.62.1.113:5054	http://92.112.181.188:5054

8.2 Autenticación

Header: X-Auth-Key: {h_instancia}

8.3 Endpoints Principales

Path	Método	Servicio	Descripción
/health	GET	Todos	Health check
/ingest	POST	Clara/Margaret	Registrar entrada
/list	GET	Clara/Margaret	Listar entradas
/flujos	GET/POST	Alfred/Jared	Gestionar flujos
/pendientes	GET	Mason	Items pendientes
/item/{id}	GET/PUT	Mason	Gestionar item
/milestones	GET	Feldman	Listar milestones
/bloques	GET	Feldman	Listar bloques
/verify/{hash}	GET	Feldman	Verificar integridad
/consolidar	POST	Feldman	Consolidar entradas

8.4 Schemas Principales

HealthResponse

{
  "service": "clara",
  "status": "ok",
  "rol": "secretaria",
  "timestamp": "ISO8601",
  "version": "1.0.0"
}

IngestResponse

{
  "success": true,
  "h_entrada": "sha256...",
  "timestamp": "ISO8601"
}

VerifyResponse

{
  "valid": true,
  "hash": "sha256...",
  "found_in": "milestone|block|entry"
}

---

SKYNET v10 - ANEXO 1 REFERENCIA TÉCNICA - 6 Enero 2026