Manual de arquitectura SDUI

Manual SDUI para Praxy AI

Idea en una frase

El servidor decide la interfaz. El cliente solo muestra árboles o “deltas” que envía el servidor—siempre tras auth, tenancy y política. Lo que sigue es agnóstico de framework: sólo cuenta la abstracción HTTP (forma del request + forma del response).

Para qué sirve

Una sola entrada — Un POST (patrón: /…/dispatch) uniforma payload, errores, telemetría y correlación.
Comandos planos (“registry”) — Un commandKey opaco ⇒ un handler estable.
Composites — Árboles de nodos (paneles, líneas de tiempo…) para no encadenar muchas llamadas desde el navegador.
Política concentrada — Cada trayecto conoce tenant (company_id o tu equivalente), roles, cupos, auditoría.

Nada delicado depende sólo del browser: quien debe ver qué lo decide el servidor.

Contrato HTTP (idea general)

Ejemplo POST …/dispatch con JSON:

{
  "commandKey": "resource.summary.card",
  "payload": { "resourceId": "acct-4491" },
  "context": { "locale": "es" }
}

Respuesta = sobre serializado que tu cliente ya entiende (árbol SDUI o lista de deltas + metadatos). El nombre exacto no importa: constancia sí.

Auth y tenancy (lenguaje simple)

Credencial válida ⇒ contexto de confianza (quién, tenant, scopes) ⇒ recién ahí despacho. Fallas ⇒ error estructurado; jamás medio-UI fugada.

Cableado — Python

Cualquier stack web basta con: validar, enriquecer contexto, llamar al núcleo. Esquema tipo FastAPI:

@app.post("/api/sdui/dispatch")
def dispatch(payload: dict, tenant_ctx: TenantContext = Depends(resolve_tenant)):
    body = validate_dispatch_body(payload)
    return dispatch_sdui(
        command_key=body["commandKey"],
        payload=body.get("payload") or {},
        context={**body.get("context", {}), **tenant_ctx.to_dict()},
    )

Flask, Django, colas serverless… la abstracción es validar → despachar → sanear → responder.

Cableado — Node.js

Mismo flujo, JSON en cable:

async function dispatchHandler(req, res) {
  const tenant = await resolveTenant(req);
  const body = validateDispatchBody(req.body);
  const envelope = await dispatchSdui({
    commandKey: body.commandKey,
    payload: body.payload ?? {},
    context: { ...(body.context ?? {}), ...tenant.toJSON() },
  });
  res.json(envelope);
}

Express, Fastify, Hono, Bun—solo pega ese contrato encima.

Dos formas de organizar el trabajo

Comandos en registry (“una receta por clave”)

Llamada con commandKey + payload; el servidor mapea a un handler determinista.

POST /api/sdui/dispatch
Content-Type: application/json

{
  "commandKey": "resource.summary.card",
  "payload": { "resourceId": "acct-4491" },
  "context": { "locale": "es" }
}

Composites (“paquetes que viajan juntos”)

Si la UX necesita orquestación, arma un árbol con hijos ordenados. Mantén orden estable si hay streaming o paginación.

Elige composites cuando importe más la correlación entre nodos que la profundidad mínima del JSON.

De intención a comando (hooks opcionales)

Capa conversacional que sugiere commandKey + trozos de payload; el despacho conserva lineage y no saltas policy.

Sobre autenticación

SSO, API keys rotativas por tenant o tokens enlazados a hardware—fusiónalas al contexto y telemetría antes del SDUI visible.

Secuencia breve

Validar → contexto tenant
Registry o composite
Emitir delta/árbol
Pasar política sobre nodos
Devolver sobre + correlación

Dispatcher SDUI y composites

Qué ocurre en un POST de despacho