system-docs/v4-archive/hst/docs/spec/HST_ROADMAP_v1.md

HST - Roadmap de Implementación

Versión: 1.0
Fecha: 2025-12-07
Estado: Borrador para maduración

---

Visión General

El sistema HST (Hash Semantic Tagging) evolucionará en 4 fases, desde especificación formal hasta una aplicación cliente universal de drag & drop.

Fase 0          Fase 1              Fase 2                 Fase 3
SPEC        →   Servidor        →   Descentralización  →   App Cliente
(Documentos)    (KVM1 Hostinger)    (Filecoin/IPFS)        (Drag & Drop)

---

Fase 0: Especificación Formal

Objetivo

Documento definitivo que describe el sistema completo antes de cualquier implementación.

Entregables

Documento	Descripción	Estado
SPEC.md	Especificación técnica completa del sistema HST	Pendiente
SCHEMA.md	Modelo de datos para NocoDB/PostgreSQL	Pendiente
TAGS_v1.csv	Listado consolidado de etiquetas (~850)	En progreso
HIERARCHY.md	Árbol jerárquico de categorías	Pendiente
RELATIONS.md	Grafo de relaciones entre etiquetas	Pendiente
API.md	Especificación de endpoints REST	Pendiente
STYLES.md	Tabla de estilos (4096 skins)	Pendiente

Contenido de SPEC.md

1. Filosofía del sistema
2. Imagen primigenia (reglas)
3. Hash maestro (H_maestro)
4. Extensiones (EXT, HSU, SP, SPU, PRJ)
5. Sistema de estilos (hash visible)
6. Cadena de metadatos (jerarquía)
7. Propiedad y acceso (H_propiedad, H_acceso)
8. Bibliotecas (sistema, empresa, usuario)
9. Pipeline de importación
10. Integración con ecosistema (SFE, IA, n8n)

Criterios de salida

• Todos los documentos revisados y aprobados
• Sin ambigüedades técnicas
• Listado de etiquetas limpio y categorizado

---

Fase 1: Servidor Centralizado

Objetivo

Primera implementación funcional en servidor KVM1 de Hostinger.

Infraestructura

KVM1 Hostinger
├── Docker
│   ├── NocoDB (metadatos)
│   ├── PostgreSQL (base de datos)
│   └── API HST (FastAPI/Node)
├── /hst/
│   ├── primigenias/{H_maestro}.png
│   └── skins/{hash_visible}.png
└── Nginx (proxy + SSL)

Componentes

Componente	Tecnología	Función
Base de datos	PostgreSQL	Almacén principal
Interfaz datos	NocoDB	Gestión visual de etiquetas
API REST	FastAPI	Consulta/servicio de etiquetas
Almacenamiento	Sistema de archivos	Imágenes primigenias y skins
Proxy	Nginx	SSL + routing
Orquestación	n8n (Alfred)	Pipelines de importación

Funcionalidades

1. Gestión de etiquetas

• CRUD completo vía NocoDB
• Validación de imagen primigenia (sin metadatos)
• Cálculo automático de H_maestro
• Generación de skins

2. API REST

GET  /api/v1/tags                    # Listar etiquetas
GET  /api/v1/tags/{h_maestro}        # Obtener etiqueta
GET  /api/v1/tags/{h_maestro}/image  # Obtener imagen
GET  /api/v1/tags/{h_maestro}/skins  # Listar skins
POST /api/v1/tags                    # Crear etiqueta
GET  /api/v1/search?q=...            # Buscar por nombre/código
GET  /api/v1/hierarchy/{ref}         # Obtener árbol jerárquico

3. Pipeline de importación

1. Leer desde Airtable (fuente actual)
2. Descargar imagen
3. Limpiar metadatos
4. Calcular SHA-256 → H_maestro
5. Generar estructura de metadatos
6. Subir primigenia
7. Generar skins (según tabla de estilos)
8. Registrar en NocoDB

4. Subdominio

• hst.tzzr.pro o tags.tzzr.pro

Criterios de salida

• API funcional con todos los endpoints
• ~850 etiquetas migradas desde Airtable
• Pipeline de importación automatizado
• Documentación de API generada

---

Fase 2: Descentralización

Objetivo

Servicio multi-usuario escalable con almacenamiento descentralizado.

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                    CAPA DE USUARIOS                      │
│  App Web  │  App Desktop  │  App Móvil  │  Extensión    │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      API GATEWAY                         │
│         Auth + Rate Limiting + Routing                   │
└─────────────────────────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│  NocoDB/PostgreSQL │ │   Redis     │ │  Filecoin/IPFS  │
│  (Índice/Metadatos)│ │   (Cache)   │ │  (Imágenes)     │
└─────────────────┘ └─────────────┘ └─────────────────┘

Componentes nuevos

Componente	Función
Filecoin/IPFS	Almacenamiento descentralizado de imágenes
CID (Content ID)	Referencia inmutable a cada imagen
Sistema de bibliotecas	Pública, privada, por usuario
Autenticación	JWT + H_propiedad
Permisos	Control por H_acceso
Rate limiting	Protección de API pública

Tipos de biblioteca

Tipo	Propiedad	Acceso	Descripción
Sistema	HST	Público	Etiquetas base universales
Empresa	Organización	Miembros	Etiquetas corporativas
Usuario	Individual	Personal	Etiquetas propias
Compartida	Múltiple	Definido	Colaboración entre usuarios

Modelo de datos extendido

Etiqueta {
  h_maestro: string (PK)
  codigo_corto: string
  nombres: { es, en, zh... }
  extension: EXT | HSU | SP | SPU | PRJ
  
  # Almacenamiento
  cid_primigenia: string      # IPFS/Filecoin
  cid_skins: [string]         # Array de CIDs
  
  # Metadatos
  cadena_metadatos: [string]  # Jerarquía de hashes
  h_propiedad: string         # Biblioteca propietaria
  h_acceso: string            # Nivel de acceso
  
  # Auditoría
  created_at: timestamp
  created_by: string
  version: int
}

Flujo de resolución

1. Cliente solicita etiqueta por H_maestro
2. API busca en caché Redis
3. Si no existe → busca en NocoDB (índice)
4. Obtiene CID de Filecoin/IPFS
5. Resuelve imagen desde red descentralizada
6. Cachea resultado
7. Retorna al cliente

Criterios de salida

• Imágenes almacenadas en Filecoin/IPFS
• Sistema de bibliotecas funcionando
• Autenticación y permisos implementados
• API pública documentada y protegida
• Al menos 3 bibliotecas de prueba (sistema, empresa, usuario)

---

Fase 3: Aplicación Cliente

Objetivo

Aplicación universal de drag & drop para usar etiquetas HST en cualquier software.

Plataformas

Plataforma	Tecnología	Prioridad
Desktop (Windows/Mac/Linux)	Tauri o Electron	Alta
Web	React/Vue	Alta
Móvil (iOS/Android)	React Native o Flutter	Media
Extensión Chrome/Firefox	WebExtension	Media
Plugin Office	Office Add-in	Baja
Plugin Figma	Figma API	Baja

Funcionalidades core

1. Navegador de etiquetas

• Vista en árbol (jerarquía)
• Vista en grid (visual)
• Búsqueda por nombre/código/hash
• Filtros por extensión/biblioteca

2. Drag & Drop

• Arrastrar etiqueta a cualquier aplicación
• Formatos de salida:
  • Imagen PNG
  • Código corto (texto)
  • Hash (texto)
  • Markdown ![nombre](url)
  • HTML <img src="url">

3. Gestión de bibliotecas

• Ver bibliotecas disponibles
• Suscribirse a bibliotecas públicas
• Crear biblioteca personal
• Sincronización offline

4. Creación de etiquetas (usuarios)

• Subir imagen primigenia
• Asignar código y nombres
• Seleccionar extensión (HSU, SPU, PRJ)
• Proponer para validación (opcional)

Flujo de usuario

1. Usuario abre app HST
2. Navega/busca etiqueta deseada
3. Arrastra etiqueta
4. Suelta en aplicación destino (Word, Figma, etc.)
5. La etiqueta se inserta como imagen/texto según contexto

Integración con sistema operativo

OS	Método
Windows	Clipboard API + Shell Extension
macOS	NSPasteboard + Finder Extension
Linux	X11/Wayland Clipboard

Modelo de monetización (futuro)

Tier	Precio	Incluye
Free	0€	Biblioteca pública, 10 etiquetas propias
Pro	5€/mes	Bibliotecas ilimitadas, skins premium
Enterprise	Personalizado	Bibliotecas privadas, soporte, SLA

Criterios de salida

• App desktop funcional (1 plataforma mínimo)
• Drag & drop funcionando en apps comunes
• Sincronización con servidor HST
• Documentación de usuario

---

Dependencias entre fases

Fase 0 ──────► Fase 1 ──────► Fase 2 ──────► Fase 3
   │              │              │              │
   │              │              │              │
   ▼              ▼              ▼              ▼
SPEC.md      Servidor       Filecoin        App
SCHEMA.md    NocoDB         Auth            Desktop
TAGS.csv     API REST       Bibliotecas     Drag&Drop
             Pipeline       Permisos        Móvil

---

H_propiedad y H_acceso (PENDIENTE DEFINIR)

H_propiedad - Definición parcial

Identifica el propietario/origen de la etiqueta.

Grupo	H_propiedad
hst	Hash de la etiqueta "hst" (sistema)
spe	Hash de la etiqueta "especificación" (sistema)
hsu	Hash del usuario creador
msu	Hash del usuario creador

H_acceso - Por definir

Llave de acceso para descarga de imagen. Relacionado con:

• Sistema de monetización futuro
• Compartición de bibliotecas entre usuarios
• Colaboración en proyectos (msu)

Notas:

• Se exploró embeber en metadatos PNG pero no está validado
• Inicialmente innecesario: la cadena estará en NocoDB
• Los grupos hsu/msu permiten compartición (por definir mecanismo)
• Diferenciación de grupos define reglas de acceso diferentes

TODO para próximas revisiones:

• Definir mecanismo de compartición de bibliotecas usuario
• Definir modelo de monetización y su relación con H_acceso
• Validar si metadatos embebidos en PNG son viables
• Definir permisos de colaboración en proyectos (msu)

---

Preguntas abiertas (a resolver)

Fase 0

• ¿Formato definitivo de código corto? → Variable según grupo
• ¿Cuántos estilos iniciales implementar?
• ¿Estructura exacta de cadena_metadatos? → Definida parcialmente

Fase 1

• ¿Dominio/subdominio para el servicio?
• ¿Migración completa desde Airtable o parcial?
• ¿Autenticación desde Fase 1 o solo Fase 2?

Fase 2

• ¿Filecoin vs IPFS vs ambos?
• ¿Modelo de costos de almacenamiento descentralizado?
• ¿Política de bibliotecas públicas (quién puede publicar)?

Fase 3

• ¿Prioridad de plataformas?
• ¿Modelo freemium desde el inicio?
• ¿Integración con marketplaces de plugins?

---

Timeline estimado

Fase	Duración estimada	Dependencias
Fase 0	1-2 semanas	Ninguna
Fase 1	2-4 semanas	Fase 0 completa
Fase 2	4-8 semanas	Fase 1 estable
Fase 3	8-12 semanas	Fase 2 funcional

Total estimado: 4-6 meses para MVP completo

---

Notas

• Este roadmap es un documento vivo que evolucionará
• Cada fase tiene criterios de salida claros
• Las fases pueden solaparse parcialmente
• Priorizar funcionalidad sobre perfección en cada fase

---

Próximo paso: Consolidar SPEC.md (Fase 0)