# 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*