15. Documentación de arquitectura: vistas, componentes, responsabilidades e interfaces
15.1 Introducción
La documentación de arquitectura describe la organización principal de un sistema de software. Explica sus partes importantes, las responsabilidades de cada una, sus relaciones, interfaces, restricciones y decisiones que condicionan la evolución del producto.
No busca reemplazar al código ni detallar cada clase. Su propósito es dar una visión comprensible de la estructura del sistema para que el equipo pueda razonar sobre cambios, riesgos, integraciones, calidad y mantenimiento.
En sistemas medianos o grandes, la arquitectura no puede entenderse solo leyendo archivos. Se necesita una documentación que muestre las decisiones estables y las relaciones relevantes entre partes.
15.2 Qué es documentar arquitectura
Documentar arquitectura significa explicar cómo está organizado el sistema y por qué. Incluye componentes, servicios, módulos, bases de datos, integraciones, capas, dependencias, protocolos, límites y responsabilidades.
También incluye restricciones y atributos de calidad: rendimiento, seguridad, disponibilidad, escalabilidad, mantenibilidad, observabilidad y tolerancia a fallas. Estos aspectos suelen influir más en la arquitectura que una funcionalidad aislada.
15.3 Vistas arquitectónicas
La imagen muestra la documentación de arquitectura como un conjunto de vistas: contexto, componentes, interfaces, datos, despliegue y decisiones. Cada vista muestra una parte del sistema desde una perspectiva distinta y ayuda a responder preguntas diferentes.
15.4 Vista de contexto
La vista de contexto muestra el sistema dentro de su entorno. Indica usuarios, sistemas externos, proveedores, canales de comunicación y límites principales. Es una de las vistas más útiles para comenzar porque permite entender qué está dentro y fuera del sistema.
Por ejemplo, un sistema de turnos puede interactuar con pacientes, profesionales, administradores, un sistema de notificaciones, un proveedor de autenticación y una plataforma de pagos. La vista de contexto no necesita mostrar clases ni tablas; muestra relaciones de alto nivel.
15.5 Vista de componentes
La vista de componentes muestra las partes principales del sistema y sus responsabilidades. Puede incluir frontend, backend, servicios, módulos internos, colas, bases de datos, adaptadores o integraciones.
Esta vista ayuda a entender dónde vive cada responsabilidad. Por ejemplo, el componente de reservas puede validar disponibilidad, el componente de agenda puede administrar horarios y el componente de notificaciones puede enviar mensajes a usuarios.
Un buen documento no solo dibuja componentes: explica qué hace cada uno, qué no hace y de qué depende.
15.6 Responsabilidades
Documentar responsabilidades permite evitar confusión entre módulos. Si dos componentes parecen encargarse de lo mismo, pueden aparecer duplicación, errores y dificultades de mantenimiento.
Una responsabilidad debe expresarse con claridad. Por ejemplo: "El servicio de agenda administra disponibilidad de profesionales" es más claro que "módulo de agenda". También conviene indicar límites: qué operaciones no debe asumir ese componente.
15.7 Interfaces
Las interfaces son puntos de comunicación entre partes del sistema o con sistemas externos. Pueden ser APIs HTTP, eventos, colas de mensajes, archivos, librerías, contratos internos o interfaces de usuario.
La documentación de arquitectura debe identificar interfaces relevantes y explicar qué información intercambian, con qué protocolo, bajo qué condiciones y qué responsabilidades tiene cada lado. Luego, una documentación de API puede detallar parámetros, respuestas y errores.
15.8 Dependencias
Las dependencias muestran qué partes necesitan a otras para funcionar. Documentarlas ayuda a evaluar impacto, riesgos y orden de despliegue. También permite detectar acoplamientos innecesarios.
No todas las dependencias tienen la misma importancia. Conviene documentar las que afectan disponibilidad, seguridad, rendimiento, despliegue o mantenimiento. Por ejemplo, depender de un proveedor externo de notificaciones puede requerir manejo de fallas y reintentos.
15.9 Vista de datos
La vista de datos describe cómo se organiza y circula la información importante. Puede incluir bases de datos, entidades principales, ownership de datos, replicación, eventos, migraciones y restricciones de privacidad.
No siempre necesita mostrar todo el modelo físico. A nivel arquitectónico interesa saber qué componentes producen, consumen o modifican datos críticos y qué reglas deben respetarse.
15.10 Vista de despliegue
La vista de despliegue muestra dónde se ejecutan las partes del sistema: servidores, contenedores, servicios cloud, redes, bases de datos, balanceadores, colas y ambientes. Es útil para operación, seguridad y análisis de disponibilidad.
Esta vista debe relacionarse con la documentación de instalación, despliegue y operación. La arquitectura explica la estructura; los procedimientos indican cómo instalar, publicar y mantener.
15.11 Restricciones y atributos de calidad
Muchas decisiones arquitectónicas surgen de restricciones: presupuesto, tecnologías permitidas, normas de seguridad, capacidad del equipo, sistemas heredados o requisitos de disponibilidad.
También surgen de atributos de calidad. Si se necesita alta disponibilidad, la arquitectura será distinta que en un sistema interno de bajo uso. Si la seguridad es crítica, se documentan controles, límites de confianza y manejo de datos sensibles.
15.12 Decisiones arquitectónicas
La documentación de arquitectura debe relacionarse con registros de decisiones. No alcanza con decir que se usa una arquitectura por capas, microservicios o una base de datos específica. Es necesario explicar por qué se eligió esa alternativa y qué consecuencias trae.
Las decisiones arquitectónicas suelen afectar muchos cambios futuros. Si quedan sin registrar, el equipo puede repetir discusiones, revertir decisiones sin contexto o introducir inconsistencias.
15.13 Nivel de detalle
El nivel de detalle debe adaptarse a la audiencia. Una vista para dirección o producto puede mostrar contexto y riesgos. Una vista para desarrollo puede incluir componentes, interfaces y dependencias. Una vista para operación puede enfocarse en despliegue, monitoreo y fallas.
Intentar satisfacer todas las audiencias en un único diagrama suele producir documentación difícil de leer. Es mejor usar vistas separadas y enlazadas.
15.14 Tabla de vistas arquitectónicas
| Vista | Pregunta que responde | Audiencia habitual |
|---|---|---|
| Contexto | ¿Con quién interactúa el sistema? | Producto, análisis, desarrollo, gestión. |
| Componentes | ¿Qué partes principales existen? | Desarrolladores, arquitectos, líderes técnicos. |
| Interfaces | ¿Cómo se comunican las partes? | Desarrollo, integración, pruebas. |
| Datos | ¿Dónde vive y circula la información? | Desarrollo, datos, seguridad, soporte. |
| Despliegue | ¿Dónde se ejecuta el sistema? | Operación, infraestructura, seguridad. |
15.15 Ejemplo: sistema de turnos
En un sistema de turnos, la documentación de arquitectura puede mostrar una aplicación web, una API backend, una base de datos, un servicio de notificaciones y un proveedor de autenticación. Cada componente tiene responsabilidades claras.
La API backend puede exponer interfaces para consultar profesionales, reservar turnos y cancelar reservas. La base de datos conserva pacientes, profesionales, agendas y turnos. El servicio de notificaciones envía confirmaciones. La documentación debe explicar estas relaciones y sus restricciones principales.
15.16 Errores frecuentes
Al documentar arquitectura suelen aparecer estos errores:
- Crear diagramas sin explicar responsabilidades ni decisiones.
- Mezclar contexto, componentes, clases y despliegue en una sola vista.
- Documentar tecnologías, pero no límites ni dependencias.
- Omitir interfaces críticas entre componentes o sistemas externos.
- No registrar restricciones ni atributos de calidad.
- No actualizar la arquitectura cuando cambia el sistema.
- Escribir documentación tan detallada que duplica el código y queda obsoleta rápido.
15.17 Qué debes recordar de este tema
- La documentación de arquitectura explica la organización principal del sistema.
- Debe incluir vistas, componentes, responsabilidades, interfaces y dependencias relevantes.
- Las vistas permiten responder preguntas distintas sin mezclar niveles de detalle.
- Las decisiones arquitectónicas deben documentar motivos y consecuencias.
- Los atributos de calidad y restricciones ayudan a entender por qué la arquitectura es así.
- La documentación de arquitectura debe mantenerse alineada con el sistema real.
- No debe duplicar todo el código, sino explicar lo que el código no comunica fácilmente.
15.18 Conclusión
La documentación de arquitectura permite comprender la estructura profunda de un sistema de software. Al organizar vistas, componentes, responsabilidades e interfaces, ayuda a evaluar impactos, comunicar decisiones y sostener la evolución del producto.
En el próximo tema estudiaremos el registro de decisiones de arquitectura y decisiones técnicas.