Curso de SAD (Software Architecture Document)

Identificar stakeholders técnicos, funcionales, operativos y de negocio.

Determinar qué información necesita cada audiencia del SAD.

Definir objetivo, alcance y límites de la arquitectura documentada.

Explicar el problema de negocio que da origen al sistema.

Documentar capacidades principales y responsabilidades generales.

Identificar actores humanos, sistemas externos y organizaciones relacionadas.

Delimitar qué está dentro y fuera del sistema.

Documentar dependencias con proveedores y servicios externos.

Definir supuestos utilizados durante el diseño.

Registrar restricciones conocidas desde el inicio.

Representar el sistema dentro de su ecosistema empresarial.

Evitar que alcance funcional y alcance arquitectónico queden ambiguos.

Comprender qué convierte un requisito en arquitectónicamente significativo.

Identificar requisitos funcionales con impacto estructural.

Identificar requisitos no funcionales que condicionan el diseño.

Analizar volumen, concurrencia, disponibilidad y criticidad.

Recoger restricciones regulatorias, tecnológicas y organizativas.

Identificar integraciones que condicionan la arquitectura.

Registrar necesidades de seguridad, privacidad y trazabilidad.

Documentar requisitos de mantenimiento y evolución.

Priorizar drivers cuando existen objetivos contradictorios.

Diferenciar requisitos obligatorios, deseables y futuros.

Relacionar drivers con decisiones arquitectónicas.

Mantener trazabilidad entre requisitos y componentes afectados.

Comprender los atributos de calidad como elementos centrales del diseño.

Documentar rendimiento, escalabilidad, disponibilidad y resiliencia.

Incorporar seguridad, privacidad y auditabilidad.

Analizar mantenibilidad, modificabilidad y extensibilidad.

Considerar interoperabilidad y portabilidad.

Incluir testabilidad, operabilidad y observabilidad.

Evaluar usabilidad cuando afecta a decisiones arquitectónicas.

Convertir atributos abstractos en escenarios medibles.

Identificar fuente, estímulo, entorno, artefacto, respuesta y medida.

Priorizar atributos de calidad según valor y riesgo.

Detectar trade-offs entre atributos incompatibles.

Utilizar escenarios de calidad para revisar la arquitectura.

Documentar restricciones tecnológicas impuestas por la organización.

Registrar lenguajes, frameworks, plataformas y bases de datos permitidas.

Definir restricciones cloud, on-premise, híbridas o regulatorias.

Documentar estándares internos de seguridad y desarrollo.

Establecer principios arquitectónicos compartidos.

Definir convenciones de naming, módulos, servicios y paquetes.

Registrar estándares de comunicación e integración.

Establecer criterios para sincronía, asincronía y eventos.

Documentar políticas de almacenamiento y persistencia.

Definir versiones soportadas y compatibilidad tecnológica.

Evitar restricciones heredadas cuya justificación ya no existe.

Mantener relación entre principios, excepciones y decisiones específicas.

Comprender por qué una arquitectura necesita registrar sus decisiones.

Diferenciar decisión, requisito, restricción, supuesto y recomendación.

Crear ADRs con contexto, decisión, alternativas y consecuencias.

Identificar decisiones que merecen un ADR y decisiones demasiado pequeñas.

Documentar alternativas descartadas y motivos.

Registrar trade-offs técnicos y de negocio.

Definir estados de ADR: propuesto, aceptado, rechazado, sustituido o deprecado.

Relacionar ADRs entre sí cuando una decisión reemplaza a otra.

Vincular ADRs con requisitos, diagramas, componentes y riesgos.

Versionar ADRs dentro del repositorio.

Utilizar ADRs durante revisiones y onboarding.

Evitar modificar retrospectivamente una decisión histórica sin dejar trazabilidad.

Comprender el enfoque C4 para representar arquitecturas a diferentes niveles.

Crear el System Context Diagram.

Identificar personas, sistemas externos y relaciones principales.

Construir el Container Diagram.

Representar aplicaciones, servicios, bases de datos y tecnologías relevantes.

Crear Component Diagrams para áreas que necesitan mayor profundidad.

Decidir cuándo resulta realmente útil llegar al nivel Code.

Mantener consistencia entre niveles del modelo.

Aplicar nomenclatura clara y orientada a responsabilidad.

Representar protocolos y relaciones cuando aportan información.

Evitar incluir detalles irrelevantes para cada nivel.

Integrar C4 dentro del SAD sin duplicar descripciones existentes.

Comprender qué aporta UML dentro de un SAD.

Crear diagramas de componentes.

Diseñar diagramas de secuencia para interacciones críticas.

Utilizar diagramas de despliegue.

Representar clases cuando son arquitectónicamente relevantes.

Modelar estados para procesos complejos.

Crear diagramas de actividad para flujos importantes.

Representar dependencias entre paquetes y módulos.

Diferenciar diagramas conceptuales de diagramas de implementación.

Seleccionar únicamente los diagramas que aportan información real.

Mantener consistencia entre UML, código y arquitectura.

Combinar UML y C4 sin duplicar el mismo concepto.

Dividir el sistema en responsabilidades arquitectónicas coherentes.

Identificar módulos, componentes, servicios, capas y subsistemas.

Documentar responsabilidades de cada elemento.

Registrar interfaces ofrecidas y dependencias consumidas.

Diferenciar dependencias permitidas y dependencias prohibidas.

Representar flujos entre presentación, aplicación, dominio e infraestructura.

Documentar arquitectura hexagonal, Clean Architecture o modelos por capas cuando proceda.

Identificar bounded contexts cuando se utilizan principios de Domain-Driven Design.

Documentar componentes compartidos y librerías internas.

Registrar dependencias de terceros.

Detectar acoplamiento excesivo y responsabilidades mezcladas.

Crear una vista lógica comprensible para desarrollo y QA.

Documentar fuentes de datos y responsabilidades de almacenamiento.

Identificar bases relacionales, NoSQL, caches, data lakes y otros repositorios.

Representar ownership de los datos.

Documentar entidades y relaciones arquitectónicamente relevantes.

Describir flujos de lectura y escritura.

Registrar replicación, particionado y distribución cuando proceda.

Documentar consistencia fuerte y eventual.

Describir estrategias de caché.

Registrar retención, archivado y eliminación.

Documentar cifrado y protección de información.

Identificar datos maestros y sistemas fuente de verdad.

Relacionar arquitectura de datos con privacidad, disponibilidad y recuperación.

Inventariar interfaces internas y externas.

Documentar APIs REST, GraphQL, SOAP, gRPC u otros mecanismos utilizados.

Registrar productores y consumidores.

Documentar autenticación y autorización de cada integración.

Definir contratos, esquemas, payloads y formatos.

Documentar versionado y compatibilidad hacia atrás.

Identificar dependencias síncronas críticas.

Registrar límites, cuotas, timeouts y políticas de reintento.

Documentar errores y contratos de fallo.

Identificar sistemas externos y responsables de cada integración.

Registrar SLAs y dependencias de terceros.

Crear diagramas específicos para integraciones complejas.

Documentar eventos de dominio, integración y sistema.

Identificar productores, consumidores, brokers y topics.

Representar colas, streams y canales.

Documentar esquemas y contratos de evento.

Registrar semánticas de entrega.

Analizar idempotencia y duplicados.

Documentar ordering y particionamiento.

Definir políticas de retry y dead-letter queues.

Representar sagas y procesos distribuidos.

Documentar consistencia eventual.

Incorporar observabilidad de mensajería.

Detectar dependencias ocultas en arquitecturas orientadas a eventos.

Crear una vista específica de seguridad.

Identificar activos y datos sensibles.

Documentar boundaries de confianza.

Representar identidad, autenticación y autorización.

Registrar roles, permisos, scopes y políticas.

Documentar cifrado en tránsito y reposo.

Identificar gestión de secretos y claves.

Representar flujos de información sensible.

Documentar auditoría y trazabilidad.

Registrar amenazas relevantes y mitigaciones.

Relacionar arquitectura con threat modeling.

Documentar requisitos regulatorios que condicionan el diseño.

Incorporar seguridad como decisión arquitectónica transversal.

Documentar entornos de desarrollo, testing, staging y producción.

Representar servidores, nodos, contenedores y clusters.

Documentar cloud regions, availability zones y datacenters.

Incluir redes, subredes, firewalls y balanceadores.

Representar Kubernetes cuando forma parte de la solución.

Documentar contenedores e imágenes.

Identificar servicios gestionados y componentes propios.

Registrar configuración y diferencias entre entornos.

Documentar DNS, certificados y endpoints.

Representar infraestructura mediante diagramas físicos.

Relacionar infraestructura con requisitos de disponibilidad y rendimiento.

Mantener coherencia entre SAD e Infrastructure as Code.

Documentar responsabilidades entre proveedor cloud y organización.

Identificar servicios IaaS, PaaS, SaaS y serverless utilizados.

Representar cuentas, subscriptions, proyectos y organizaciones cloud.

Documentar regiones y restricciones de residencia de datos.

Identificar dependencias propietarias del proveedor.

Registrar conectividad entre cloud y datacenter.

Documentar escenarios híbridos.

Representar arquitecturas multi-cloud cuando sean necesarias.

Analizar portabilidad y vendor lock-in.

Documentar costes arquitectónicamente significativos.

Registrar escalado y elasticidad.

Relacionar decisiones cloud con seguridad, resiliencia y compliance.

Identificar cargas críticas y patrones de utilización.

Documentar usuarios concurrentes y volúmenes esperados.

Registrar objetivos de latencia y throughput.

Representar puntos potenciales de saturación.

Documentar escalado vertical y horizontal.

Analizar caching, pooling y procesamiento asíncrono.

Registrar límites de bases de datos y sistemas externos.

Documentar estrategias de rate limiting.

Diseñar escenarios de crecimiento.

Relacionar capacidad con costes.

Registrar resultados relevantes de pruebas de rendimiento.

Mantener hipótesis de capacidad actualizadas.

Documentar objetivos de disponibilidad.

Identificar componentes críticos y puntos únicos de fallo.

Representar redundancia y distribución.

Documentar health checks y recuperación automática.

Registrar estrategias de failover.

Definir timeout, retry, circuit breaker y bulkhead cuando proceda.

Documentar degradación controlada del servicio.

Registrar RTO y RPO.

Diseñar backup y restore.

Documentar disaster recovery.

Representar dependencias de infraestructura críticas.

Definir procedimientos de continuidad ante fallos de terceros.

Documentar estrategia de logging.

Definir métricas técnicas y de negocio relevantes.

Representar trazas distribuidas.

Identificar correlation IDs y propagación de contexto.

Documentar dashboards esenciales.

Registrar alertas y condiciones de escalado.

Definir health endpoints y checks operativos.

Documentar observabilidad de APIs, colas, bases de datos y dependencias externas.

Relacionar observabilidad con SLOs y SLIs.

Incorporar procedimientos básicos de troubleshooting.

Documentar ownership operativo.

Conectar arquitectura con runbooks y respuesta a incidentes.

Documentar correctamente un monolito tradicional.

Representar un monolito modular.

Diferenciar límites internos y límites desplegables.

Documentar arquitecturas de microservicios.

Registrar ownership de servicios.

Representar comunicación síncrona y asíncrona.

Documentar service discovery, gateways y mecanismos compartidos.

Identificar datos compartidos y anti-patrones.

Registrar dependencias transversales.

Comparar trade-offs entre modularidad y distribución.

Documentar estrategias de evolución de monolito a servicios.

Evitar representar microservicios como simples cajas desconectadas del contexto real.

Abordar sistemas sin documentación fiable.

Recopilar información desde código, configuración, infraestructura y operación.

Entrevistar a desarrolladores y responsables históricos.

Construir gradualmente el mapa de componentes.

Identificar integraciones desconocidas.

Documentar bases de datos compartidas y dependencias ocultas.

Diferenciar arquitectura prevista y arquitectura realmente implementada.

Registrar deuda técnica y restricciones heredadas.

Crear vistas AS-IS.

Diseñar arquitectura TO-BE.

Elaborar roadmap de transición entre ambas.

Priorizar documentación según riesgo y valor.

Identificar riesgos técnicos, operativos y organizativos.

Registrar probabilidad, impacto y mitigaciones.

Diferenciar riesgo conocido de supuesto pendiente de validar.

Documentar deuda técnica estructural.

Registrar deuda tecnológica y obsolescencia.

Identificar dependencias con proveedores críticos.

Analizar riesgos de escalabilidad.

Documentar riesgos de seguridad y continuidad.

Registrar decisiones temporalmente aceptadas.

Relacionar deuda con roadmap y coste futuro.

Mantener un registro arquitectónico de riesgos.

Utilizar el SAD como herramienta para priorizar inversiones técnicas.

Mantener documentación arquitectónica junto al código cuando resulte apropiado.

Utilizar Markdown, AsciiDoc u otros formatos textuales.

Crear diagramas con Mermaid, PlantUML o herramientas equivalentes.

Versionar SAD y ADRs mediante Git.

Trabajar con ramas, pull requests y revisiones documentales.

Aplicar revisión técnica a cambios arquitectónicos.

Generar documentación estática automáticamente.

Integrar validaciones en CI/CD.

Comprobar enlaces, sintaxis y generación de diagramas.

Relacionar releases de software con versiones del SAD.

Mantener historial de evolución arquitectónica.

Reducir documentación manual duplicada mediante automatización.

Definir quién es responsable de cada sección.

Establecer frecuencia y condiciones de actualización.

Incorporar revisión arquitectónica al ciclo de desarrollo.

Crear Architecture Review Boards cuando el contexto lo requiere.

Definir criterios de aceptación arquitectónica.

Utilizar checklists para evaluar completitud.

Revisar consistencia entre código, infraestructura y documentación.

Detectar diagramas obsoletos.

Controlar excepciones a principios y estándares.

Integrar SAD con Definition of Done.

Establecer métricas de calidad documental.

Mantener el documento útil durante todo el ciclo de vida.

Seleccionar un sistema empresarial representativo.

Definir propósito, alcance, contexto y stakeholders.

Identificar requisitos arquitectónicamente significativos.

Documentar restricciones y principios.

Elaborar escenarios de atributos de calidad.

Crear el System Context Diagram.

Crear los niveles de Container y Component necesarios.

Incorporar diagramas UML donde aporten información adicional.

Diseñar la vista lógica de módulos, servicios y componentes.

Documentar arquitectura de datos y ownership.

Inventariar APIs, eventos e integraciones.

Crear una vista de seguridad con boundaries, identidad y controles.

Documentar infraestructura, redes y despliegue.

Describir rendimiento, capacidad y escalabilidad.

Definir disponibilidad, resiliencia, backup, RTO y RPO.

Crear la estrategia de observabilidad y operación.

Registrar los ADRs más importantes de la solución.

Crear el registro de riesgos y deuda técnica.

Definir arquitectura AS-IS y TO-BE si existe modernización.

Versionar SAD, ADRs y diagramas mediante Git.

Preparar proceso de revisión, aprobación y mantenimiento.

Presentar el SAD defendiendo decisiones, alternativas, trade-offs y evolución prevista.