From 36f87ca9b79034dc1ae9b11395dca133f92635b1 Mon Sep 17 00:00:00 2001 From: ARCHITECT Date: Wed, 31 Dec 2025 19:28:36 +0000 Subject: [PATCH] =?UTF-8?q?Add=2007=5FINTERFACES=20-=20Documentaci=C3=B3n?= =?UTF-8?q?=20de=20interfaces=20desplegadas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- 07_INTERFACES/07_INTERFACES.md | 775 +++++++++++++++++++++++++++++++++ 1 file changed, 775 insertions(+) create mode 100644 07_INTERFACES/07_INTERFACES.md diff --git a/07_INTERFACES/07_INTERFACES.md b/07_INTERFACES/07_INTERFACES.md new file mode 100644 index 0000000..c60e31d --- /dev/null +++ b/07_INTERFACES/07_INTERFACES.md @@ -0,0 +1,775 @@ +# 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//status # Estado de un servicio + +# URL Shortener integrado +POST /api/shorten # Acortar URL +GET /api/urls # Listar URLs +GET /s/ # Redirección +GET /api/url//stats # Estadísticas +``` + +### Gestión + +```bash +# 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/ # Detalle item +PUT /api/mason/item/ # Actualizar item +POST /api/mason/item//resolve # Resolver → Feldman +POST /api/mason/item//descartar # Descartar + +# Feldman +GET /api/feldman/milestones # Listar milestones +GET /api/feldman/blocks # Listar bloques +GET /api/feldman/verify/ # Verificar hash + +# Flujos +GET /api/flujos # Listar flujos +POST /api/flujos # Crear flujo +POST /api/flujos//ejecutar # Ejecutar flujo +GET /api/ejecuciones # Historial + +# Admin +GET /api/admin/servicios # Estado servicios +GET /api/admin/logs/ # Logs +POST /api/admin/restart/ # Reiniciar +``` + +### Gestión + +```bash +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/ # Detalle entrada +``` + +### Request de Ingesta + +```json +POST /api/v1/ingest +{ + "contenido": "texto o datos", + "origen": "manual|api|flujo", + "metadata": { + "usuario": "id", + "timestamp": "ISO8601" + } +} +``` + +### Response + +```json +{ + "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/ # Detalle flujo +POST /api/v1/flujo//ejecutar # Ejecutar flujo +GET /api/v1/ejecuciones # Historial ejecuciones +``` + +### Estructura de Flujo + +```json +{ + "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/ # Detalle item +PUT /api/v1/item/ # Actualizar item +POST /api/v1/item//resolve # Enviar a Feldman +POST /api/v1/item//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/ # Detalle bloque +POST /api/v1/consolidate # Consolidar cola → bloque +GET /api/v1/verify/ # Verificar integridad +GET /api/v1/merkle/ # Obtener prueba Merkle +GET /api/v1/stats # Estadísticas +``` + +### Estructura de Bloque + +```json +{ + "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:** + +```json +{ + "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:** + +```json +{ + "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:** + +```json +{ + "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:** + +```json +{ + "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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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*