Baukaalm/system-design-first

Diseño de sistema primero

La mayoría de tickets describen qué construir y ocultan las preguntas que deciden si sobrevive al contacto con producción: cuántos usuarios, con qué frecuencia, cuántos datos, qué sucede cuando una dependencia es lenta, quién tiene la verdad cuando dos escritores compiten. Esta habilidad hace explícitas esas preguntas antes de que se escriba código, en una forma que el autor de la tarea pueda leer y debatir.

El paso es: alcance → estimación → diseño de alto nivel → inmersión profunda → cierre, aplicado al trabajo real: existe un código base, un autor con intención y un presupuesto. El objetivo es una imagen nítida de la función desde el punto de vista del sistema.

Responde en el idioma en que escribe el usuario. El informe es para ellos, no para ti.

1. Medir la profundidad primero

Sobrediseñar una corrección tipográfica es tan malo como subdiseñar un flujo de pago. Elige el nivel, dilo en una línea y gasta en consecuencia.

Nivel	Tarea típica	Qué produces
L0 – trivial	Cambio de copia, renombre, ajuste de estilo, error obvio con corrección local	Nada extra. Una oración como máximo si existe un riesgo oculto ("esta etiqueta también se almacena en caché en la CDN durante 24h"). Luego solo haz la tarea.
L1 – cambio local	Nuevo campo, nuevo filtro, cambio pequeño de endpoint, un hook, un ajuste de consulta	Una verificación de diseño en línea de 3 a 7 líneas: qué toca, la carga que soporta, la única cosa que podría morder (N+1, invalidación de caché, paginación, idempotencia). Luego implementa.
L2 – función	Nueva pantalla con flujo de datos, nuevo endpoint + almacenamiento, notificaciones, búsqueda, exportación, integración con un tercero	El informe de diseño (sección 4), aproximadamente una página. Luego implementa según el informe.
L3 – subsistema	Nuevo servicio, canal en tiempo real, pipeline de eventos, modelo de datos multiinquilino, migración de una ruta crítica, cualquier cosa con "escala" en el ticket	Informe completo más una inmersión profunda por componente riesgoso, alternativas consideradas, ruta de migración, qué medir después del lanzamiento.

Señales que empujan una tarea hacia arriba un nivel: latencia visible para el usuario, escritores concurrentes, fan-out (un evento → muchos destinatarios), crecimiento ilimitado de una tabla o lista, límites de tarifa de terceros, dinero, PII, cualquier cosa que se ejecute en un horario, o soluciones "temporales" que obviamente se quedarán. Señales que la empujan hacia abajo: herramientas internas con un puñado de usuarios, datos que caben en memoria para siempre, experimentos con feature flags que tienen un interruptor de apagado.

Si el usuario pide explícitamente una revisión de diseño o un análisis más profundo, trátalo como L3 independientemente del tamaño.

2. El paso, paso a paso

Trabaja en estos en orden. Para L1 comprímelos en unas pocas líneas; para L2/L3 cada paso se convierte en una sección del informe. references/framework.md tiene las listas de verificación de preguntas para cada paso; léelo la primera vez que ejecutes una pasada L2+ en una sesión.

Paso 1 — Comprender y definir el alcance

• Reformula la función en un párrafo como la ve el sistema: actores, desencadenantes, entradas, salidas, efectos secundarios.
• Separa los requisitos funcionales (qué hace) de los no funcionales (qué tan bien: escala, latencia, disponibilidad, consistencia, durabilidad, seguridad, costo, operabilidad). Los tickets casi nunca establecen el segundo tipo; infiérelos del contexto del producto y di que son inferidos.
• Escribe qué está fuera del alcance, para que el informe no crezca silenciosamente.
• Recopila la intención del autor: texto del ticket, descripción del PR, comentarios, diseños vinculados, ADRs existentes, cómo se construyeron funciones similares en este repositorio. El autor generalmente tiene un diseño en la cabeza; sácalo a la superficie en lugar de reemplazarlo.
• Pregunta al usuario solo preguntas que cambien el diseño materialmente (ej. "¿esto debe ser visible en un segundo, o está bien un minuto?"). Para todo lo demás, establece una suposición y continúa; las suposiciones van al informe.

Paso 2 — Estimar

Los números convierten opiniones en decisiones. Haz una estimación de servilleta incluso cuando el ticket no tenga ninguna; references/estimation.md contiene los números de referencia (escalera de latencia, potencias de dos, nueves de disponibilidad, capacidades por nodo) y ejemplos resueltos.

• Usuarios / inquilinos → diarios activos → acciones por día → QPS promedio y pico (pico suele ser 2-5× el promedio, más para flujos abruptos como "todos abren la aplicación a las 9:00").
• Relación lectura/escritura, tamaño de carga útil → almacenamiento por día / año, ancho de banda.
• Crecimiento: ¿cuál es el número en 12 meses si el producto tiene éxito?
• Donde existan números reales (analíticas, recuentos de filas de BD, paneles existentes, límites de configuración), úsalos y cita la fuente; de lo contrario, da un rango y márcalo como una suposición.

Luego usa los números para matar patrones, no solo para justificarlos: "a 30 escrituras/s una tabla Postgres con un índice está bien; una cola no es necesaria para rendimiento, solo si queremos reintentos y desacoplamiento del proveedor de correo electrónico".

Paso 3 — Mapear el diseño actual (as-is)

Lee el código antes de describirlo. Nombra archivos reales, módulos, tablas, endpoints, trabajos, cachés, colas. No inventes componentes.

• ¿Qué componentes toca la función? Dibuja el flujo de datos en un diagrama de texto corto (cliente → BFF → servicio → Postgres, evento → cola → trabajador).
• ¿Dónde está el estado y quién lo posee (BD, caché, almacenamiento del cliente, URL)?
• ¿Qué primitivas existentes se pueden reutilizar (una tabla de outbox, un ejecutor de trabajos, un caché de consultas, un hub WebSocket, un componente Paginación compartido)?
• Rutas críticas, cuellos de botella conocidos, SPOF existentes, límites actuales (límites de tarifa, tamaños de página, tiempos de espera) que la función hereda.
• Para una tarea de frontend, el as-is sigue siendo un sistema: capa de obtención de datos, política de caché, límites de bundle, transporte en tiempo real — ver references/frontend.md.

Paso 4 — Proponer el diseño objetivo (to-be)

Comienza con la intención del autor. Si es sólida, dilo y ajústala; si entra en conflicto con los números o con un modo de falla conocido, muestra el conflicto con su consecuencia y ofrece el cambio más pequeño que lo solucione. El autor decide; tu trabajo es hacer visible la compensación.

• Diseño de alto nivel como diagrama de texto, más el contrato de API (endpoints / eventos / mensajes con formas) y el modelo de datos (tablas, claves, índices, retención).
• Para cada elección no trivial nombra el patrón y la alternativa que rechazaste, con la razón vinculada a los números del Paso 2. references/patterns.md es el catálogo: escalado, almacenamiento en caché, async/colas, almacenes de datos y consistencia, estilos de API y transporte en tiempo real, limitación de tasa, generación de ID, confiabilidad, observabilidad — cada uno con "usar cuando / evitar cuando / compensaciones".
• Mapea la función a un sistema canónico cuando encaje uno ("esto es un sistema de notificaciones: cola + trabajadores por canal + dedup", "esto es fan-out de feed de noticias", "esto es un limitador de tasa"). La última sección del catálogo enumera las formas canónicas y sus bloques de construcción estándar. La analogía le da al lector un punto de referencia conocido y una lista de verificación de lo que tales sistemas suelen necesitar.
• Prefiere las primitivas existentes del repositorio y el diseño más simple que cumpla con los números con margen. Di explícitamente qué mejoras se difieren y qué señal las desencadenaría ("añade una réplica de lectura cuando el p95 de esta consulta supere los 200 ms o la tabla supere las 50M filas").

Paso 5 — Inmersión profunda en lo que puede fallar

Para L2 elige la una o dos partes más riesgosas; para L3 recorre todas. Preguntas estándar, en orden aproximado de frecuencia con la que muerden:

1. Concurrencia e idempotencia — envíos duplicados, reintentos, dos escritores, entrega al menos una vez. ¿Dónde está la clave de idempotencia? ¿Cuál es la restricción única?
2. Consistencia — quién lee datos obsoletos y por cuánto tiempo; ¿es aceptable?; ruta de invalidación de caché; leer-tus-propias-escrituras.
3. Fallo de una dependencia — proveedor caído, cola retrasada, módulo remoto que no se carga. Tiempos de espera, reintentos con jitter, interruptor de circuito, degradación gradual, qué ve el usuario.
4. Puntos calientes — claves calientes, inquilinos de celebridades, listas sin límite, N+1, escaneos completos de tabla, índice faltante, rebaño atronador en la expiración de caché.
5. Crecimiento — la tabla/lista/cola que crece sin límite; retención, archivado, paginación (cursor sobre desplazamiento), particionamiento.
6. Migración e implementación gradual — backfill, período de doble escritura, feature flag, ruta de reversión, cambios de contrato compatibles hacia atrás.
7. Seguridad y privacidad — autorización a nivel de datos (aislamiento de inquilino), PII en registros/colas, limitación de tasa en endpoints públicos, validación de entrada.
8. Observabilidad — qué métrica prueba que funciona (SLI), qué alerta se activa cuando no funciona, qué registrar para depurar una sola solicitud.

Paso 6 — Cerrar, ofrecer la visualización

Los diagramas cuestan tokens, por lo que son optativos. El informe mismo usa solo flujos de texto de una línea (cliente → API → Postgres).

Para L2 y L3, termina el informe con una pregunta, junto con las preguntas abiertas, en el idioma del usuario:

¿Dibujar la arquitectura? 1 — diagrama as-is / to-be en la terminal · 2 — más una carpeta de diseño (Mermaid + architecture.html) · 3 — no

• Dibuja solo después de que el usuario elija 1 o 2, siguiendo references/visualization.md. No esperes la respuesta para comenzar a implementar; si el usuario sigue adelante sin responder, es un "no".
• Omite la pregunta y dibuja inmediatamente solo cuando el usuario ya haya pedido un diagrama, una imagen, una visualización o la carpeta de diseño.
• Si nadie puede responder (una ejecución no interactiva, CI, una evaluación), no dibujes y no preguntes; menciona en una línea que los diagramas están disponibles bajo petición.
• Nunca lo ofrezcas para L0 o L1.

Produce el informe (siguiente sección), luego continúa con la tarea: implementa según el informe, mantén el informe también en la descripción del PR/MR, y enumera las preguntas abiertas para el autor en lugar de decidirlas en silencio.

3. Reglas de juicio

• Números antes que patrones. Nunca recomiendes Kafka, sharding, CQRS, un clúster de caché dedicado o microservicios sin una estimación que los necesite. La simplicidad es una característica; la complejidad debe ganarse su lugar.
• Explica, no sermonees. Cada recomendación lleva un "porque" de una oración que el autor puede verificar. Las analogías con sistemas canónicos son bienvenidas; las listas de palabras de moda no.
• Respeta el diseño del autor. Presenta desacuerdos como "X causará Y con una carga Z; la solución más barata es W". Si aún prefieren su camino, implementa su camino y anota el riesgo en el informe.
• El código existente es evidencia. Léelo. Un informe que describe componentes que no existen es peor que ningún informe.
• Separa lo imprescindible de lo bueno tener. Marca cada recomendación como "necesario ahora", "necesario antes del lanzamiento" o "necesario con ~N usuarios".
• El frontend cuenta. El almacenamiento en caché del cliente, la paginación, las actualizaciones optimistas, el transporte en tiempo real, los límites de bundle y el aislamiento de fallos son diseño de sistema; references/frontend.md cubre la versión del lado del cliente de cada paso.
• Mantente en el idioma y vocabulario del usuario. Traduce los nombres de patrones si el equipo lo hace; mantén el término en inglés entre paréntesis la primera vez.

4. El informe de diseño

Usa esta estructura para L2 y L3. Mantén los encabezados; elimina una sección solo cuando esté genuinamente vacía y dilo en una línea. Apunta a una página para L2. references/brief-template.md tiene un ejemplo completo y la forma compacta de L1.

# Informe de diseño: <función>

**Profundidad:** L2 · **Estado:** propuesta · **Intención del autor:** <una línea>

## 1. Alcance
Funcional: ...
No funcional (inferido a menos que se indique): escala · latencia · disponibilidad · consistencia · seguridad · costo
Fuera del alcance: ...
Suposiciones: ...

## 2. Estimaciones
| Métrica | Ahora | +12 meses | Fuente |
| --- | --- | --- | --- |
| DAU / inquilinos | | | |
| QPS pico (lectura / escritura) | | | |
| Crecimiento de almacenamiento | | | |
Conclusión: <lo que los números permiten / prohíben>

## 3. Diseño actual (as-is)
<flujo de texto de una línea> · propiedad del estado · primitivas reutilizables · límites heredados
Archivos: ...

## 4. Diseño objetivo (to-be)
<flujo de texto de una línea> · contrato de API · modelo de datos · analogía de sistema canónico
Elecciones de patrón: <patrón> — porque <razón>; rechazado <alternativa> porque <razón>.

## 5. Riesgos e inmersiones profundas
1. <riesgo> → mitigación (necesario ahora / antes del lanzamiento / con N)
...

## 6. Implementación gradual, migración, observabilidad
Flags, backfill, reversión · SLI + alerta · qué registrar

## 7. Preguntas abiertas para el autor
- ...
- ¿Dibujar la arquitectura? 1 — diagrama en terminal · 2 — más carpeta de diseño · 3 — no

## 8. Plan de implementación
Pasos ordenados, cada uno lo suficientemente pequeño para revisar.

5. Referencias — qué leer cuándo

Archivo	Léelo cuando
references/framework.md	Primera pasada L2+ en una sesión: listas de verificación de preguntas por paso, lista NFR, cómo extraer la intención del autor, antipatrones de análisis.
references/estimation.md	Cada vez que necesites un número: escalera de latencia, nueves, capacidades por nodo, matemáticas de QPS/almacenamiento, ejemplos resueltos.
references/patterns.md	Elegir o justificar un patrón; mapear una función a un sistema canónico (chat, feed, notificaciones, autocompletado de búsqueda, sincronización de archivos, limitador de tasa, almacén KV, generador de ID, pagos, ...). Tiene una tabla de contenidos.
references/frontend.md	La tarea es un cambio de UI / SPA / micro-frontend: caché de obtención de datos, paginación, tiempo real, límites de bundle, aislamiento de fallos, números del lado del cliente.
references/brief-template.md	Escribir el informe: ejemplo completo L2 y la forma compacta en línea L1.
references/visualization.md	Solo después de que el usuario haya pedido diagramas (Paso 6). Dibujarlos: reglas de diagrama de caja en terminal, convenciones de Mermaid, diseño de carpeta de diseño, cómo llenar assets/architecture.html.