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

Add 07_INTERFACES - Documentación de interfaces desplegadas

Browse Source 
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>
This commit is contained in:
ARCHITECT
2025-12-31 19:28:36 +00:00
parent 3960067337
commit 36f87ca9b7
1 changed files with 775 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

775
07_INTERFACES/07_INTERFACES.md Normal file
View File

@@ -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/<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
```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/<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
```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/<id> # 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/<id> # Detalle flujo
POST /api/v1/flujo/<id>/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/<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
```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*