High-Level Design
Una síntesis con alcance declarado
High-Level Design es, en el Atlas, la práctica de desarrollar y comunicar una representación deliberadamente acotada y un conjunto de decisiones significativas sobre elementos principales, responsabilidades, fronteras, interacciones e implicaciones de ejecución y deployment, suficientes para razonar sobre un sistema frente a sus drivers.
HLD se usa de distintas maneras entre organizaciones; esta es una definición de trabajo, no una semántica estandarizada para toda la industria. El resultado puede combinar texto, modelos, decisiones y evidencia. No se define por un template, un número de páginas ni una herramienta de diagramación.
software-architecture trata las estructuras y compromisos mismos; HLD ayuda a desarrollarlos y representarlos al nivel elegido. Una descripción incompleta no hace desaparecer decisiones ya realizadas. Tampoco un dibujo convincente prueba que el sistema implementado conserve las propiedades declaradas.
High level relativo a qué
El nivel depende del alcance y la pregunta. Payments puede ser una unidad al estudiar Commerce; al diseñar Payments, autorización, conciliación e integración con un proveedor pueden ser elementos generales. boundaries y granularity ayudan a declarar sistema observado y significado de las partes.
High level no significa vago. Un HLD puede omitir clases y precisar inequívocamente quién autoriza un pago, qué confirma una respuesta y qué ocurre con un resultado incierto. Esas precisiones importan más que representar cada objeto del programa.
Detailed design y low-level design suelen referirse a decisiones de implementación dentro de compromisos más amplios, pero la terminología y la frontera varían. Un índice, formato o mecanismo de concurrencia puede merecer atención en HLD si determina viabilidad. El criterio es architectural-significance, no prohibir detalles por su apariencia técnica.
Entradas que justifican lo representado
requirements-to-architecture aclara necesidades e implicaciones; design-process desarrolla y evalúa candidatos. HLD utiliza objetivos, architectural-drivers, constraints, escenarios relevantes y preguntas abiertas. No exige que toda la información exista definitivamente antes de dibujar una primera propuesta.
En brownfield necesita distinguir situación actual, objetivo y transición. legacy-systems conserva comportamiento y consumidores; migration-strategy impide representar un destino como si ya existiera una trayectoria segura hacia él. Una vista puede mostrar intención o realidad observada, pero debe identificar cuál.
quality-attributes-overview y quality-attribute-scenarios permiten decidir qué compromisos necesitan hacerse visibles. Si una entrega independiente es un driver, omitir versiones y dependencias puede invalidar el razonamiento. Si tenancy no forma parte del problema, no hace falta inventar un modelo multitenant para completar una plantilla.
Contexto, responsabilidades y relaciones
El contexto identifica actores, consumidores, sistemas externos y dependencias que no controlamos. Explicar qué queda fuera evita asignar a Commerce garantías que pertenecen al proveedor. Una región o protocolo contractual necesita aparecer junto a la decisión que restringe, sin determinar automáticamente todo el diseño.
decomposition y modularity permiten expresar responsabilidades y decisiones protegidas. Orders, Payments, Inventory y Shipping pueden representar capacidades lógicas; no se deduce que sean cuatro servicios, procesos, containers o deployment units. Una vista interna necesita otra interpretación explícita de sus elementos.
components y connectors conservan esas distinciones. Una caja debe tener significado para la vista; una flecha necesita explicar una interacción relevante. Llamada local, mensaje, evento, acceso compartido y sincronización tienen consecuencias distintas. Etiquetar todo como «API» deja sin resolver confirmación, espera y recuperación.
interfaces permite representar contratos importantes y quién los gobierna, sin inventariar todos los endpoints. Una importación de código y una llamada de runtime no deben interpretarse como la misma relación solo porque ambas se dibujen con flechas.
Varias vistas para preguntas diferentes
Rozanski y Woods explican el uso de views y viewpoints para atender preocupaciones distintas, evitando un modelo único sobrecargado. El enfoque Views and Beyond del SEI organiza documentación alrededor de vistas relevantes y agrega información que las atraviesa. Se usan como fundamento de comunicación, no como un paquete obligatorio de diagramas.
ISO/IEC/IEEE 42010:2022 distingue arquitectura de su descripción y no prescribe un proceso de producción ni un formato. HLD no equivale a declarar conformidad con ese estándar. Según la pregunta pueden servir contexto, estructura, interacción, autoridad de datos o deployment, con correspondencias comprensibles entre ellas.
Una vista lógica puede conservar responsabilidades y otra mostrar cómo se asignan a unidades de ejecución. Si ambas usan Payments con significados diferentes, aclarar el mapping. Agregar vistas sin mantener sus relaciones puede aumentar documentación y dejar contradicciones ocultas.
common-pitfalls examina el salto de caja lógica a deployable y la ilusión de que un dibujo completa la arquitectura. design-exercises permite contrastar una representación con cambios de requisitos o fallos, revisando qué compromisos explica y cuáles siguen sin evidencia.
C4 como opción, no como definición
C4 ofrece niveles de estructura y diagramas complementarios; recomienda utilizar los que aportan valor. Un contexto y un container diagram pueden comunicar partes útiles de un HLD, sin resolver todas sus decisiones ni sustituir riesgos y rationale.
En el vocabulario de C4, container puede ser una aplicación o un data store; no debe leerse automáticamente como Docker container. Su diagrama no desarrolla por sí solo todos los aspectos de clustering, failover o deployment. Usarlo requiere conservar su terminología, sin imponer C4 al Atlas ni convertir su nivel en la definición universal de high level.
Decision Axes como preguntas de cobertura
architecture-decision-axes permite revisar omisiones que afectarían drivers. No todos los ejes necesitan igual detalle ni establecen una secuencia:
| Preocupación de Commerce | Decisiones que conviene hacer visibles |
|---|---|
| Responsabilidades y propagación del cambio. | decomposition y dependency-structure: qué parte gobierna cada obligación y qué conocimiento cruza sus límites. |
| Checkout y resultado conjunto. | communication y coordination: aceptación, finalización, orden y tratamiento de resultados incompletos. |
| Estado e impacto compartido. | data-ownership e isolation: autoridad, copias y qué efectos continúan compartidos. |
| Clientes y entrega. | tenancy y deployment: sharing pertinente, unidades actualizables y combinaciones que deben coexistir. |
| Trabajo y crecimiento. | execution-model y scaling: triggers, duración, unidad ampliable y límites externos. |
La tabla navega preguntas, sin redefinir ejes. Autoridad de Payments no exige una base física exclusiva. Desplegar una unidad por separado no demuestra deployability independiente. Un worker puede cambiar cuándo termina trabajo sin imponer eventos, y comunicación async no significa necesariamente broker.
Si el proveedor puede agotar conexiones compartidas, dibujar procesos separados no prueba contención. Si browsing crece más que checkout, identificar recursos y unidades ampliables es más útil que agregar caches o sharding por costumbre. Los mecanismos necesitan una necesidad y evidencia.
estimation aproxima las cantidades que condicionan esas decisiones, con supuestos y unidades visibles. trade-off-analysis compara consecuencias de fronteras candidatas; el HLD conserva el resultado y las razones relevantes sin sustituir la evidencia por una etiqueta de profile o llenarse de cálculos que no cambian el diseño.
Profiles, tecnología y decisiones explícitas
architecture-profiles ayuda a sintetizar una dirección, pero «Microservices» no declara autoridad, coordinación, contratos ni operación reales. Es necesario explicar las respuestas elegidas. Una variante con deployment común también necesita comunicar sus límites internos y recursos compartidos.
La tecnología puede omitirse cuando no discrimina candidatos o incluirse si materializa una constraint, compatibilidad, comportamiento de plataforma, costo u obligación operacional. Neutralidad absoluta tampoco es un objetivo: ocultar que un contrato exige un engine puede hacer inviable la propuesta.
No convertir HLD en una lista de framework, broker, base y runtime. Vincular cada elección significativa con driver, alternativas y consecuencias permite revisarla. Un ADR puede conservar una decisión individual; el HLD sintetiza relaciones entre decisiones, sin reducirse a una colección de registros.
Commerce: una representación que permite discutir
Este ejemplo es una síntesis del Atlas. Orders gobierna el lifecycle de la orden; Payments declara estado válido del pago; Inventory gobierna stock y reservas; Shipping atiende la preparación del envío. El proveedor SOAP queda fuera de Commerce y restringe la integración de Payments.
Un recorrido relevante puede mostrar solicitud de checkout, autorización, reserva y trabajo de envío posterior, precisando qué confirma cada señal. No fija un orden universal ni oculta las alternativas: qué reservar primero y qué prometer al cliente dependen de los compromisos de negocio y fallos aceptables.
La representación necesita distinguir pago solicitado, autorización confirmada y resultado todavía desconocido. Inventory debe conservar autoridad frente a reservas concurrentes; Shipping no debería interpretar una aceptación de trabajo como evidencia de pago terminado. Esas preguntas requieren más que flechas del caso feliz.
Una revisión cruzada comprueba que las vistas no prometan cosas incompatibles. Si la vista lógica reserva a Payments la escritura sobre pagos y otra permite acceso directo desde Orders, hay una decisión pendiente o una contradicción que explicar. Si el flujo espera confirmación inmediata pero la vista de ejecución muestra trabajo diferido, precisar qué espera realmente el usuario. Esta lectura conjunta permite detectar huecos sin expandir cada implementación. La revisión debe conservar tanto la intención como la evidencia todavía necesaria para sostenerla bajo el escenario elegido.
Para explorar delivery pueden compararse módulos en un deployment común con una frontera entregable separada de Payments, según el driver aclarado. La segunda alternativa exige revisar versiones, operación y efectos de red; la primera puede localizar cambios internos sin satisfacer una exigencia auténtica de release independiente.
Browsing y checkout pueden compartir o separar capacidad según el workload y el límite observado. El HLD registra el supuesto que sostiene esa elección, sin inventar dimensionamiento exacto. Representar una sola base tampoco autoriza a Orders a modificar estado privado de Payments.
Saber qué profundizar y qué dejar abierto
Un HLD útil conserva decisiones, rationale, constraints, supuestos, riesgos y alternativas significativas. No necesita cada clase, tabla, endpoint o parámetro. Sí necesita señalar si un dato omitido podría cambiar una garantía o hacer inviable el diseño.
deep-dives investiga preguntas seleccionadas: cómo evitar overselling, cómo recuperar una autorización incierta o qué limita el pico requerido. La relación es bidireccional: HLD hace visible una pregunta; la investigación puede modificar responsabilidades, interacción o deployment. No son fases cerradas ni una obligación de profundizar cada caja.
architectural-significance permite distinguir un detalle delegable de uno decisivo. Declarar una cuestión pendiente no resuelve su riesgo: indicar qué decisión depende de ella, cómo se investigará y qué compromiso debe esperar. Puede quedar incertidumbre aceptada si el próximo incremento no depende ya de resolverla.
Suficiencia y revisión
Hay detalle suficiente cuando los stakeholders relevantes pueden razonar sobre responsabilidades, interacciones significativas, qualities, restricciones y riesgos del alcance. Número de páginas, cajas o diagramas no mide completitud. Una revisión puede mostrar un conflicto y requerir reformular el objetivo antes de construir.
El HLD se revisa cuando cambia evidencia, intención o contexto. evolutionary-architecture conecta ese aprendizaje con adaptación guiada; no lo convierte en un blueprint inmutable ni en documentación sin obligación de contrastarse con lo implementado.
La síntesis HLD → pregunta significativa → Deep Dive → evidencia y decisión → HLD revisado pertenece al Atlas. design-process contiene ambos movimientos; requirements-to-architecture mantiene el origen de drivers. system-design-practice conserva sus recorridos sin equiparar high level con vaguedad, stack, un diagrama C4 o cantidad de servicios.