Un caso de estudio: diseñar un SaaS pieza por pieza

Diseñar una arquitectura no consiste en enumerar servicios, sino en tomar una secuencia de decisiones defendibles y dejar constancia de por qué cada una era preferible a su alternativa más razonable. Todo lo que hemos visto en el nivel se juega ahora sobre un caso concreto: una herramienta de gestión documental por suscripción, con varias organizaciones aisladas entre sí, un panel que muestra actividad reciente, subida de ficheros que pueden ser grandes y avisos que deben aparecer sin recargar la página. Es un producto deliberadamente mediano, del tamaño que casi cualquier equipo construye al menos una vez, y su interés está justamente en que ninguna de sus piezas es exótica: la dificultad está entera en el reparto.

El enunciado y sus restricciones

El producto guarda documentos para organizaciones. Cada usuario pertenece a una organización y solo ve lo suyo; el panel muestra los últimos movimientos y unas cuantas cifras agregadas; los documentos se suben desde el navegador y pueden llegar a varios cientos de megabytes; cuando un compañero sube algo, los demás lo ven aparecer sin refrescar. Hay además un plan de suscripción con límites por organización y una factura mensual.

De ese párrafo salen cuatro restricciones que gobiernan todo lo demás, y conviene escribirlas antes de tocar ninguna tecnología. Primera: el aislamiento entre organizaciones es un requisito de corrección, no una opción de diseño, así que la clave de inquilino tiene que aparecer en cada consulta y cada clave de objeto. Segunda: los ficheros grandes no pueden atravesar el Worker, porque materializarlos costaría memoria y tiempo de pared que no hay motivo para gastar. Tercera: el panel se lee muchísimo más de lo que se escribe, así que sus cifras admiten estar unos segundos desfasadas. Cuarta: las notificaciones son efímeras y deben llegar a quien esté mirando ahora, no a quien vuelva mañana.

flowchart TD
N[navegador] --> W[worker unico]
W --> A[assets del panel]
W --> KV[kv plan y limites]
W --> D1[d1 metadatos y permisos]
N -->|put firmado directo| R2[r2 documentos]
W --> Q[queue documento subido]
Q --> C[consumidor]
C --> R2
C --> D1
C --> DO[durable object de la organizacion]
DO -->|websocket| N
WF[workflow de facturacion] --> D1
style W fill:#89b4fa,color:#11111b
style DO fill:#cba6f7,color:#11111b

Los tres caminos del producto

Un producto se entiende mejor por sus caminos que por su diagrama, porque el diagrama enseña qué existe y el camino enseña qué cuesta. Estos tres concentran prácticamente todo el tráfico y todo el riesgo.

El primero es cargar el panel. Debe resolverse con una lectura de sesión, una lectura de plan y una única consulta agregada a D1, y el resultado se cachea unos segundos por organización porque nadie va a notar la diferencia. Tres subpeticiones y unos pocos milisegundos de CPU: ese es el presupuesto, y cualquier funcionalidad que pretenda añadir una cuarta consulta tiene que justificarse.

El segundo es subir un documento, y es el que más gente diseña mal. La tentación es que el fichero entre por el Worker, se valide allí y se escriba en R2, que funciona perfectamente con ficheros pequeños y se rompe con los grandes. La alternativa correcta invierte el flujo: el Worker no toca los bytes, solo autoriza. Emite una URL firmada de vida corta contra el endpoint compatible con S3, registra la intención en D1 y devuelve; el navegador sube directo y avisa al terminar.

import { AwsClient } from "aws4fetch";

app.post("/api/documentos/subida", async (c) => {
  const usuario = c.get("usuario")!;
  const clave = `org/${usuario.orgId}/${crypto.randomUUID()}`;

  const r2 = new AwsClient({
    accessKeyId: c.env.R2_ACCESS_KEY_ID,
    secretAccessKey: c.env.R2_SECRET_ACCESS_KEY,
    service: "s3",
  });

  const destino = new URL(
    `https://${c.env.R2_CUENTA}.r2.cloudflarestorage.com/${c.env.R2_BUCKET}/${clave}`,
  );
  destino.searchParams.set("X-Amz-Expires", "600");
  const firmada = await r2.sign(new Request(destino, { method: "PUT" }), {
    aws: { signQuery: true },
  });

  await c.env.DB.prepare(
    "INSERT INTO documentos (clave, org, autor, estado) VALUES (?, ?, ?, 'pendiente')",
  ).bind(clave, usuario.orgId, usuario.id).run();

  return c.json({ url: firmada.url, clave });
});

Fíjate en dos detalles que no son cosméticos. El primero es que la clave del objeto empieza por el identificador de la organización: el aislamiento del inquilino queda grabado en el nombre, de modo que un fallo de autorización posterior no permite alcanzar el fichero de otro cliente por accidente. El segundo es que la fila se crea en estado pendiente antes de que exista el objeto, lo que da un rastro para limpiar las subidas abandonadas y una forma barata de aplicar el límite del plan antes de firmar nada.

El tercer camino es la notificación. Cuando el consumidor de la cola termina de procesar el documento, avisa al Durable Object de la organización, que mantiene las conexiones abiertas de quienes están mirando el panel en ese instante. Un objeto por organización es la granularidad correcta aquí: por usuario habría demasiados y no compartirían nada, y uno global sería un cuello de botella con todos los inquilinos serializados en el mismo hilo.

async function avisar(env: Env, orgId: string, evento: unknown): Promise<void> {
  const id = env.SALA_ORG.idFromName(`org:${orgId}`);
  await env.SALA_ORG.get(id).fetch("https://interno/emitir", {
    method: "POST",
    body: JSON.stringify(evento),
  });
}

Los tres caminos comparten una propiedad que no es casual: en ninguno de ellos el usuario espera a un trabajo que no forma parte de la promesa. El panel espera a una consulta agregada porque sin ella no hay panel; la subida espera a una firma porque sin ella no hay destino; la notificación no la espera nadie, porque llega después por definición. Cuando un producto crece, la degradación empieza casi siempre por la erosión de esa disciplina: alguien añade al camino del panel una llamada al proveedor de facturación para mostrar los días restantes del plan, y una funcionalidad de dos líneas convierte una ruta de tres subpeticiones en una ruta que depende de un tercero.

Lo que dejamos fuera, y cuándo volver

Un diseño sin límites declarados no es un diseño, es una lista de deseos. Estas cuatro renuncias son deliberadas y cada una lleva pegada la señal que obligaría a reabrir la discusión, porque la señal es la parte útil: sin ella, la renuncia se convierte en un olvido.

Hay además una quinta renuncia que no cabe en una tarjeta porque no es técnica: hemos aceptado que la facturación viva dentro del mismo proyecto en lugar de aislarla en un servicio con su propio ciclo de despliegue y su propio acceso restringido. Es defendible mientras el equipo sea pequeño y todo el mundo tenga el mismo nivel de acceso, y deja de serlo en el momento exacto en que la empresa contrata a la primera persona que debe poder tocar el panel sin poder tocar los cobros. La señal, en este caso, no es una métrica: es una incorporación.

Merece la pena notar lo que no aparece en ninguna de las cuatro tarjetas: ninguna renuncia se justifica por rendimiento teórico ni por elegancia. Todas se justifican por tamaño actual y todas tienen un umbral medible. Esa es la diferencia entre un diseño que envejece bien y uno que se reescribe entero a los dieciocho meses, cuando nadie recuerda qué supuestos lo sostenían y la única salida honesta parece empezar de cero.