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
- [x] ¿Formato definitivo de código corto? → Variable según grupo
- [ ] ¿Cuántos estilos iniciales implementar?
- [x] ¿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)