Future Platform Roadmap¶

Fecha de congelamiento: 2026-06-02

Objetivo¶

Congelar la vision futura oficial de la plataforma sobre la base ya cerrada y operativa al 2026-06-01, sin implementar nuevas capas todavia.

Este documento es contractual para futuras etapas. Si una iniciativa futura lo contradice, primero debe actualizar este documento y luego la documentacion derivada.

Alcance de esta congelacion¶

solo documenta
no instala herramientas nuevas
no modifica infraestructura actual
crea estructura documental de tenants
no crea bases nuevas
no crea APIs nuevas
no crea agentes nuevos

Estado actual¶

La arquitectura tecnologica base ya esta cerrada y validada documentalmente en VERDE.

Infraestructura y plataformas activas¶

VPS Hostinger
Docker
OpenClaw
Nginx Proxy Manager
Portainer
Grafana
Prometheus
Thanos
Alertmanager
Knowledge Portal
Git Sync VPS -> GitHub
Dashboard Ejecutivo de Infraestructura
DNS / TLS
Observabilidad
Runbooks
Gobierno documental

Servicios publicados¶

https://doc.alpuntodeventa.com.ar/
https://developers.alpuntodeventa.com.ar/
https://grafana.alpuntodeventa.com.ar/
https://openclaw.alpuntodeventa.com.ar/
https://portainer.alpuntodeventa.com.ar/

Servicios internos¶

Prometheus
Thanos
Alertmanager

Estado de arquitectura¶

la base actual queda congelada como foundation operativa
la infraestructura actual no se reabre mientras no exista aprobacion formal de una nueva etapa
Multi-Tenant Foundation queda implementada como base documental y estructural, sin capas runtime nuevas
API Platform queda implementada como base documental y contractual, sin capas runtime nuevas
Business Knowledge Platform no esta implementada

Arquitectura actual¶

La arquitectura vigente responde al modelo de una sola base operativa con servicios tecnicos compartidos y una capa documental ya preparada para crecer.

flowchart TD
    internet[Internet] --> npm[Nginx Proxy Manager]
    npm --> portal[Knowledge Portal]
    npm --> openclaw[OpenClaw]
    npm --> grafana[Grafana]
    npm --> portainer[Portainer]

    grafana --> thanos[Thanos Query]
    thanos --> prometheus[Prometheus]
    thanos --> objectstore[Thanos Object Store Local]
    prometheus --> alertmanager[Alertmanager]

    prometheus --> exporters[Exporters y probes]
    exporters --> docker[Docker runtime]
    docker --> vps[VPS Hostinger]

    docs[Governance + Runbooks + Knowledge Platform] --> portal
    git[GitHub] --> sync[Git Sync VPS]
    sync --> portal

Lectura de la arquitectura actual¶

NPM es la unica puerta de publicacion aprobada
Knowledge Portal, OpenClaw, Grafana y Portainer son los frontends publicados
Prometheus, Thanos y Alertmanager permanecen internos
Governance y Knowledge Platform ya son la autoridad documental viva
Git sigue siendo la fuente de verdad del portal

Arquitectura objetivo¶

La evolucion futura aprobada a nivel conceptual es la siguiente:

flowchart TD
    infra[Infraestructura]
    mt[Multi-Tenant Layer]
    data[Data Foundation]
    api[API Platform]
    bkp[Business Knowledge Platform]
    dash[Business Dashboards]
    agents[Agents Layer]
    orch[Future Orchestrator]

    infra --> mt
    mt --> data
    data --> api
    api --> bkp
    bkp --> dash
    dash --> agents
    agents --> orch

Capa 1 - Infraestructura¶

Base operativa compartida donde viven VPS, Docker, reverse proxy, observabilidad, portal documental, runbooks y gobierno tecnico.

Casos de uso:

publicar frontends seguros por NPM
operar stacks Docker aislados
observar salud tecnica y alertas
mantener trazabilidad documental y runbooks

Capa 2 - Multi-Tenant Layer¶

Capa contractual de aislamiento logico entre alcance global y alcance por tenant.

Casos de uso:

separar alpuntodeventa de ladirecta
registrar ownership y alcance de cada activo
impedir que usuarios, datos, credenciales y dashboards de un tenant aparezcan en otro

Capa 3 - Data Foundation¶

Base transaccional y analitica recomendada para datos estructurados futuros, con PostgreSQL como tecnologia objetivo.

Casos de uso:

persistir entidades de negocio por tenant
unificar datos operativos y de negocio
habilitar Row Level Security
construir una base estable para APIs y dashboards

Capa 4 - API Platform¶

Capa de exposicion controlada sobre la data foundation.

Modelo recomendado inicial:

PostgreSQL -> PostgREST -> NPM -> API

Modelo futuro extendido:

PostgreSQL -> PostgREST -> Kong Gateway -> clientes externos

Casos de uso:

publicar APIs globales
publicar APIs por tenant
exponer permisos, auditoria y contratos OpenAPI

Capa 5 - Business Knowledge Platform¶

Capa futura para gobernar entidades y relaciones de negocio sin mezclar esa semantica con la observabilidad tecnica.

Casos de uso:

catalogar clientes, productos, marcas, ventas y canales
consolidar definiciones oficiales por tenant
sostener trazabilidad entre dato, API, dashboard y agente

Capa 6 - Business Dashboards¶

Capa futura de visualizacion de negocio basada en datos persistidos, no en metricas tecnicas de Prometheus.

Casos de uso:

ventas por tenant
rentabilidad
capital por marca
rotacion
clientes y canales

Capa 7 - Agents Layer¶

Capa futura de agentes especializados con separacion entre agentes globales y agentes por tenant.

Casos de uso:

agente global de infraestructura
agente global de documentacion
agente global de seguridad
agente comercial por tenant
agente financiero por tenant
agente de stock por tenant

Capa 8 - Future Orchestrator¶

Capa futura de coordinacion entre agentes, workflows, APIs, conocimiento y eventos.

Casos de uso:

coordinar un flujo de negocio entre ventas, stock y alertas
disparar acciones a partir de eventos multi-tenant
gobernar aprobaciones, auditoria y ejecucion automatizada

Principios de diseno¶

Estos principios quedan congelados como contratos oficiales de evolucion.

Contrato 1 - Datos nuevos¶

Todo dato nuevo debe indicar:

scope
tenant_id

Contrato 2 - Dashboards nuevos¶

Todo dashboard nuevo debe indicar:

scope
tenant_id

Contrato 3 - Documentacion nueva¶

Toda documentacion nueva debe indicar:

owner
scope
tenant_id

Contrato 4 - APIs nuevas¶

Toda API nueva debe tener:

OpenAPI
documentacion
ejemplos
permisos
auditoria

Contrato 5 - Aislamiento de tenants¶

Ningun tenant puede acceder a datos de otro tenant.

Contrato 6 - Credenciales¶

Toda credencial debe pertenecer a uno de estos alcances:

global
tenant especifico

Reglas de gobierno¶

Regla 1 - Authority first¶

La autoridad documental sigue siendo docs/, con docs/governance/ como capa viva de operacion actual y este documento como vision futura oficial.

Regla 2 - No mezclar estados¶

La infraestructura actual cerrada no debe describirse como multi-tenant implementada mientras siga siendo solo objetivo futuro.

Regla 3 - Cada activo debe declarar alcance¶

Todo activo futuro debe poder clasificarse como:

global
tenant

Y debe declarar:

owner
scope
tenant_id cuando aplique

Regla 4 - Gobierno antes de cierre¶

Ninguna futura etapa se considera terminada si no actualiza:

este roadmap futuro
ROADMAP.md
PROJECT-STATE.md
la navegacion del portal si cambia la estructura visible

Regla 5 - Observabilidad tecnica separada¶

Las metricas tecnicas de infraestructura siguen perteneciendo a la capa de observabilidad, mientras que los indicadores de negocio deben nacer de la data foundation o del data warehouse futuro.

Multi-Tenant Foundation¶

Esta capa queda definida solo a nivel documental.

Modelo objetivo¶

Global¶

infraestructura
observabilidad
gobierno
seguridad
documentacion compartida

Tenants¶

alpuntodeventa
ladirecta
futuras empresas

Estructura objetivo¶

text tenants/ ├─ alpuntodeventa/ ├─ ladirecta/ └─ futura_empresa/

Identidad minima obligatoria¶

Todo activo multi-tenant futuro debe declarar:

tenant_id
scope
ownership

Casos de uso¶

separar dashboards de Al Punto de Venta y La Directa
separar credenciales por tenant
separar datos, logs y workflows por tenant
habilitar crecimiento de futuras empresas sin rehacer la foundation

Knowledge Portal Multi-Tenant¶

La URL actual a mantener es:

https://doc.alpuntodeventa.com.ar/

Estructura futura¶

Global
Alpuntodeventa
La Directa

Modelos posibles¶

acceso abierto
acceso por rutas
acceso por subdominios
Authentik
Authelia

Criterio documental¶

El portal actual sigue siendo valido como portal principal, pero en el futuro debera poder distinguir contenido global de contenido por tenant sin mezclar propiedad ni visibilidad.

Grafana Multi-Tenant¶

Modelo objetivo documental:

text Grafana ├─ Global ├─ Alpuntodeventa └─ La Directa

Regla objetivo¶

root ve todo
cada usuario ve unicamente su tenant

Casos de uso¶

tablero ejecutivo global
tablero operativo de alpuntodeventa
tablero operativo de ladirecta

OpenClaw Multi-Tenant¶

Evolucion conceptual futura de OpenClaw, sin implementacion todavia.

Separaciones obligatorias¶

agentes por tenant
workflows por tenant
datos por tenant
credenciales por tenant
logs por tenant
dashboards por tenant

Ejemplos reales futuros¶

un agente comercial de alpuntodeventa no debe leer pedidos de ladirecta
un workflow financiero de ladirecta no debe usar credenciales globales por defecto si existe una credencial propia del tenant
los logs de automatizaciones deben poder filtrarse por tenant_id

Data Foundation¶

Tecnologia recomendada:

PostgreSQL

Documento rector:

docs/architecture/DATA-FOUNDATION.md

Reglas minimas¶

Toda tabla multi-tenant debe incluir:

tenant_id
source_system
created_at
updated_at
created_by
updated_by
record_status

Y ademas debe incluir:

external_id si aplica
sync_batch_id si aplica

Regla de seguridad recomendada¶

usar Row Level Security para garantizar aislamiento por tenant

Ejemplo conceptual¶

sql create table sales_orders ( id bigserial primary key, tenant_id text not null, external_id text not null, source_system text not null, sync_batch_id text, created_at timestamptz not null default now(), updated_at timestamptz not null default now(), created_by text not null, updated_by text not null, record_status text not null default 'active', total_amount numeric(14,2) not null );

API Platform¶

Arquitectura recomendada¶

flowchart LR
    pg[PostgreSQL] --> postgrest[PostgREST]
    postgrest --> npm[NPM]
    npm --> api[API]

Evolucion futura¶

flowchart LR
    pg[PostgreSQL] --> postgrest[PostgREST]
    postgrest --> kong[Kong Gateway]
    kong --> clients[Clientes externos]

Contratos obligatorios¶

OpenAPI
ejemplos
permisos
auditoria
documentacion navegable

API Documentation Platform¶

Herramienta recomendada:

Scalar

Alternativa:

Swagger UI

Capacidades esperadas¶

lectura de OpenAPI
ejemplos
playground
pruebas desde navegador
APIs globales
APIs por tenant
separacion sandbox vs productivo
integracion futura con el Knowledge Portal
estructura por tenant, internas y externas

Documento rector¶

docs/architecture/API-DOCUMENTATION-PLATFORM.md

Alertas Multi-Tenant¶

Capa tecnica¶

Prometheus
Thanos
Alertmanager

Tipos de metricas¶

metricas tecnicas
metricas operativas

Tipos de alertas¶

alertas tecnicas
alertas de negocio

Ejemplos futuros¶

pedidos pendientes por tenant_id
WooCommerce sin ventas por tenant_id
stock critico por tenant_id
APIs caidas por tenant_id

Business Knowledge Platform¶

Esta capa no esta aprobada para implementar todavia, pero queda roadmapeada.

Dominios futuros¶

Clientes
Productos
Marcas
SKU
Ventas
Canales
Proveedores
Finanzas
Capital por marca
Blindaje por marca
Fondos de reinversion
Logistica

Business Dashboards¶

Fuente principal objetivo¶

PostgreSQL
Data Warehouse futuro

Regla¶

no usar Prometheus como fuente principal para dashboards de negocio

Ejemplos futuros¶

ventas
rentabilidad
capital
rotacion
clientes

Agents Layer¶

Agentes globales futuros¶

agente infraestructura
agente documentacion
agente seguridad

Agentes por tenant futuros¶

agente comercial
agente financiero
agente stock
agente pedidos
agente alertas

Roadmap por etapas¶

Etapa A - Congelacion de foundation actual¶

mantener la arquitectura base cerrada
seguir operando con Governance, Knowledge Platform y Observability
no abrir implementacion multi-tenant todavia

Etapa B - Definicion formal Multi-Tenant Foundation¶

estado: cerrada documentalmente al 2026-06-02
taxonomia global vs tenant: aprobada
tenant_id, scope y ownership: definidos como contrato
estructura documental objetivo: creada para alpuntodeventa y ladirecta
pendiente intencional: datos, APIs, dashboards, agentes y credenciales runtime

Etapa C / Etapa 14 - Data Foundation Multi-Tenant¶

estado: cerrada documentalmente al 2026-06-02
documento rector creado: docs/architecture/DATA-FOUNDATION.md
estrategia inicial recomendada: tablas compartidas con tenant_id obligatorio
dominios de datos iniciales: clientes, potenciales clientes, productos, SKU, marcas, categorias, pedidos, ventas, canales, proveedores, finanzas, capital por marca, alertas, workflows, agentes e integraciones
fuentes clasificadas por: realidad actual comprobada, futuro previsto y pendiente de validar
seguridad definida para: tenant_id, source_system, auditoria, minimo privilegio y RLS futuro
pendiente intencional: evolucionar del sandbox controlado a runtime gobernado, y despues abrir APIs, dashboards, alertas y agentes

Etapa C.1 / Etapa 15.2 - PostgreSQL Sandbox Multi-Tenant¶

estado: sandbox validado en VPS al 2026-06-02
implementacion entregada en: infra/data-foundation/postgres-sandbox/
objetivo: validar aislamiento de datos entre alpuntodeventa y ladirecta
restricciones: sin PostgREST, sin Scalar, sin datos reales, sin exposicion publica
pendiente intencional: endurecer operacion, backup y continuidad del sandbox sin convertirlo en uso productivo

Etapa C.2 / Etapa 15.3 - PostgREST Sandbox Multi-Tenant¶

estado: sandbox interno implementado al 2026-06-02
implementacion entregada en: infra/data-foundation/postgrest-sandbox/
objetivo: validar RLS y lectura REST multi-tenant sobre el PostgreSQL sandbox
diseno actual: primera validacion con runtimes internos fijos por rol sobre red Docker interna y sin publicacion de puertos
resultado tecnico buscado: probar PostgreSQL -> PostgREST -> OpenAPI sin exponer endpoints a Internet
pendiente intencional: consolidar auth real con JWT, claims tenant_id y posterior integracion con Scalar

Etapa C.3 / Etapa 15.4 - Tenant Security Sandbox¶

estado: sandbox interno validado con JWT al 2026-06-02
implementacion entregada en: infra/data-foundation/postgrest-sandbox/
objetivo: consolidar seguridad sandbox multi-tenant con JWT, claims, roles y RLS
diseno actual: runtime interno unico de PostgREST, claim role para asumir rol SQL, claim tenant_id para reforzar RLS, claim scope aplicado por recurso en db-pre-request y secreto fuera de Git
restricciones: sin exposicion publica, sin Scalar, sin Kong, sin API keys productivas, sin datos reales y sin usar todavia developers.alpuntodeventa.com.ar

Etapa D - API Platform¶

estado: cerrada documentalmente al 2026-06-02
documento rector creado: docs/architecture/API-PLATFORM.md
arquitectura inicial recomendada: PostgreSQL -> PostgREST -> Nginx Proxy Manager -> API
arquitectura futura recomendada: PostgreSQL -> PostgREST / APIs propias -> API Gateway futuro -> clientes internos y externos
contratos definidos para: scope, tenant_id, owner, permisos, scopes, auditoria y OpenAPI
seguridad futura definida para: RLS, roles de base, JWT o API keys, claims con tenant_id y minimo privilegio
pendiente intencional: implementar PostgREST, OpenAPI vivo, Scalar y publicacion segura sobre el sandbox o su sucesor gobernado

Etapa D.1 - API Documentation Platform¶

estado: cerrada documentalmente al 2026-06-02
documento rector creado: docs/architecture/API-DOCUMENTATION-PLATFORM.md
decision recomendada: Scalar como opcion principal y Swagger UI como alternativa
arquitectura objetivo documentada: PostgreSQL -> PostgREST / APIs propias -> OpenAPI -> Scalar -> API Documentation Portal
contrato obligatorio definido para: OpenAPI, owner, metodo, endpoint, parametros, ejemplos, permisos, scopes, sensibilidad y estado
reglas futuras de prueba definidas para: tokens controlados, sin secretos visibles, datos de prueba, entornos sandbox y auditoria futura
DNS/documentation portal ya publicado: developers.alpuntodeventa.com.ar
pendiente intencional: evolucionar del portal documental sandbox actual hacia pruebas controladas, auth publica aprobada y futura separacion sandbox vs productivo sin exponer PostgREST

estado: validada en VPS y cerrada sin exportes inseguros al 2026-06-02
objetivo: refinar el contrato generado por PostgREST antes de instalar Scalar
resultado actual: metadata SQL humana aplicada en runtime, contrato objetivo documentado, evaluacion de superficie completada y contrato interno validado sin endpoints indebidos
decision: mantener tablas directas del sandbox en 15.5 y posponer vistas API para una necesidad concreta de 15.6
restriccion: developers.alpuntodeventa.com.ar ya esta en uso como portal documental seguro; no debe reutilizarse para exponer PostgREST ni APIs reales sin una nueva etapa aprobada

Etapa E - Business Knowledge Platform¶

modelar dominios de negocio
catalogar entidades y relaciones
enlazar datos, APIs y dashboards

Etapa F - Business Dashboards¶

construir dashboards por tenant
separar dashboards tecnicos de dashboards de negocio

Etapa G - Agents Layer¶

especializar agentes globales
especializar agentes por tenant
unir agentes con datos y APIs gobernadas

Etapa H - Future Orchestrator¶

coordinar workflows entre capas
consolidar automatizacion auditada de extremo a extremo

Decisiones ya tomadas¶

la base actual queda congelada como foundation operativa
la base documental multi-tenant ya existe y es obligatoria para futuras capas
Prometheus, Thanos y Alertmanager siguen internos
Knowledge Portal actual se mantiene en https://doc.alpuntodeventa.com.ar/
la evolucion futura debe ser multi-tenant, no multi-instancia improvisada
la data foundation recomendada es PostgreSQL
el documento rector de datos es docs/architecture/DATA-FOUNDATION.md
la API platform recomendada nace con PostgREST
el documento rector de APIs es docs/architecture/API-PLATFORM.md
el gateway futuro recomendado es Kong
la documentacion de APIs recomendada es Scalar
la plataforma oficial de documentacion de APIs queda definida en docs/architecture/API-DOCUMENTATION-PLATFORM.md
dashboards de negocio no deben depender de Prometheus
toda evolucion futura debe declarar scope, tenant_id y ownership

Decisiones pendientes¶

cuando abrir formalmente la implementacion de Multi-Tenant Foundation
taxonomia final de tenants iniciales y naming oficial
nombramiento formal de owner humano para alpuntodeventa y ladirecta
modelo final de acceso del Knowledge Portal
modelo final de multi-tenancy en Grafana
estrategia final de separacion multi-tenant en OpenClaw
diseno fisico definitivo de PostgreSQL
aprobacion del gateway Kong
aprobacion final de Scalar vs Swagger UI
momento de instalacion real del portal interactivo de APIs
diseno de alertas de negocio por tenant
aprobacion formal de la futura Business Knowledge Platform
aprobacion formal del Future Orchestrator

Relacion con la documentacion actual¶

Este documento complementa y extiende:

Regla final¶

Hasta que se apruebe una nueva etapa, la plataforma sigue teniendo dos realidades validas y separadas:

presente operativo cerrado
futuro objetivo congelado documentalmente

No deben mezclarse.