Plantilla de documentación de arquitectura de software (gratis)

Así se suele escribir un documento de arquitectura: llega una ingeniera nueva, pregunta cómo encaja el sistema, y alguien promete «dejarlo bien escrito». Busca una plantilla de documentación de arquitectura de software, encuentra un Word de cuarenta páginas de 2012 o un PDF universitario, rellena la mitad y no vuelve a abrirlo. Un año después, la siguiente persona nueva lo encuentra, se fía de él y se equivoca.

El problema rara vez es la falta de una plantilla. Son las plantillas que lo piden todo, así que nada se termina, y los documentos sin responsable, así que nada se actualiza. La plantilla de abajo es ligera a propósito: un archivo Markdown, nueve secciones, cada una ahí porque alguien que la lea la va a necesitar. Cópiala en tu repositorio, sin registro ni descarga. Después lee las notas sección por sección sobre qué va en cada parte y cómo evitar que quede obsoleta.

Para qué sirve un documento de arquitectura (y quién lo lee)

Un documento de arquitectura responde a las preguntas que el código no responde rápido: para qué sirve el sistema, con qué se comunica, cómo está dividido, por qué está dividido así y qué se sabe que es frágil. No es una especificación de diseño de una funcionalidad ni una referencia de API.

Tiene cinco tipos de lector, y ayuda escribir pensando en ellos por su nombre:

Si una sección de tu documento no le sirve a ninguno de ellos, bórrala. Esa regla hace más por la calidad de la documentación que cualquier plantilla.

Una nota sobre los nombres: «documento de arquitectura», «system design document» (SDD) y «software architecture document» (SAD) se usan para más o menos lo mismo. Las plantillas de SDD suelen escribirse por proyecto o por funcionalidad e incluyen diseño detallado; un documento de arquitectura describe el sistema tal como es y cambia con él. La plantilla de aquí es del segundo tipo.

La plantilla (un bloque de Markdown)

Cópiala en docs/architecture.md (o ARCHITECTURE.md en la raíz) y rellénala. Todo lo que está entre ángulos es un marcador. Borra cualquier sección que no aplique en lugar de dejarla vacía.

# <Nombre del sistema>: arquitectura

| | |
|---|---|
| Responsable | <equipo o persona encargada de que esto sea cierto> |
| Última revisión | <AAAA-MM-DD> |
| Próxima revisión | <AAAA-MM-DD, o "con cada cambio en las secciones 3-5"> |
| Estado | <borrador / vigente / en sustitución por X> |

## 1. Contexto y alcance

<Dos o tres frases: qué hace el sistema, para quién y por qué existe.>

**Usuarios**
- <Rol>: <qué hacen con el sistema>

**Sistemas externos**
- <Sistema>: <qué enviamos o recibimos, protocolo>

**Fuera de alcance**
- <Cosas que la gente cree que hace este sistema, pero no hace>

**Diagrama de contexto de sistema (nivel C4 1)**
<Enlace o inserción. El sistema como una caja, cada tipo de usuario, cada sistema externo.>

## 2. Objetivos de calidad

Las tres a cinco cualidades que ganan cuando entran en conflicto entre sí, por orden de prioridad.

| Prioridad | Cualidad | Escenario concreto |
|---|---|---|
| 1 | <p. ej., Disponibilidad> | <p. ej., El checkout sigue funcionando cuando el servicio de recomendaciones está caído> |
| 2 | <p. ej., Latencia> | <p. ej., p95 del checkout por debajo de 2 s con 500 pedidos/minuto> |
| 3 | <p. ej., Facilidad de cambio> | <p. ej., Un nuevo método de pago sale sin tocar el order service> |

## 3. Restricciones

Cosas que no elegimos, pero con las que tenemos que vivir.
- <p. ej., Se ejecuta en la plataforma Kubernetes de la empresa>
- <p. ej., Los datos de clientes se quedan en la UE>
- <p. ej., Servicios backend solo en Go o Java>

## 4. Arquitectura

**Diagrama de contenedores (nivel C4 2)**
<Enlace o inserción. Cada unidad desplegable y cada almacén de datos, con tecnología y protocolos.>

| Contenedor | Tecnología | Responsabilidad | Responsable |
|---|---|---|---|
| <App web> | <SPA en React> | <Qué hace> | <Equipo> |
| <API> | <Go> | <Qué hace> | <Equipo> |
| <Base de datos> | <PostgreSQL> | <Qué almacena> | <Equipo> |

**Diagramas de componentes (nivel C4 3)**
<Solo para el contenedor, o los dos, con los que una persona nueva tendría problemas. Enlace o inserción.>

**Flujos clave**
<Los dos o tres escenarios que más importan, como pasos numerados o como diagrama dinámico C4.>

1. <Actor> -> <Contenedor>: <qué ocurre>
2. <Contenedor> -> <Contenedor>: <qué ocurre, protocolo, síncrono o asíncrono>

## 5. Decisiones clave

Los registros completos están en <docs/adr/>. Esto es el índice.

| ADR | Decisión | Estado | Fecha |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <p. ej., Una base de datos por servicio> | Aceptada | <AAAA-MM-DD> |
| [ADR-002](adr/002-<slug>.md) | <p. ej., Kafka para los eventos de pedido> | Aceptada | <AAAA-MM-DD> |

## 6. Aspectos transversales

Cómo gestiona el sistema en conjunto lo que toca a todos los contenedores. Una o dos líneas cada uno, con un enlace al detalle.
- **Autenticación y autorización:** <dónde ocurre, qué token>
- **Observabilidad:** <logs, métricas, trazas, dónde mirar>
- **Gestión de errores y reintentos:** <convenciones, idempotencia>
- **Datos y privacidad:** <dónde están los datos personales, retención>

## 7. Despliegue y operación

- **Entornos:** <producción, staging, ...> y en qué se diferencian
- **Dónde se ejecuta:** <cloud, región, clúster>
- **Runbooks:** <enlace>
- **Dashboards y alertas:** <enlace>

## 8. Riesgos y deuda técnica

| Riesgo o deuda | Impacto si ocurre | Plan | Responsable |
|---|---|---|---|
| <p. ej., Stock reservado antes del pago, sin compensación> | <Reservas fantasma tras pagos fallidos> | <Añadir liberación en caso de fallo, T4> | <Equipo> |

## 9. Glosario

| Término | Significado aquí |
|---|---|
| <Pedido> | <Definición tal como la usa el negocio> |

Esa es toda la plantilla. Rellena para un sistema de unos diez contenedores, suele ocupar unas pocas páginas. Si la tuya es mucho más larga, probablemente parte de su contenido debería estar en un documento enlazado y no en este.

Sección por sección

Cabecera: responsable y fecha de revisión

Las cuatro líneas de arriba importan más que cualquier sección de debajo. Responsable dice quién corrige el documento cuando está mal. Última revisión le dice al lector cuánto puede fiarse de él. Un documento que dice «última revisión hace catorce meses» es honesto; uno que no dice nada parece al día cuando no lo está.

1. Contexto y alcance

Empieza aquí, porque todas las demás secciones dependen del límite. Enumera cada tipo de usuario y cada sistema externo, incluidos los que das por hechos (proveedor de identidad, servicio de email, pasarela de pago). La lista fuera de alcance ahorra más reuniones que cualquier otra cosa del documento: ahí escribes que este sistema no gestiona devoluciones, aunque todo el mundo crea que sí.

El diagrama es un diagrama de contexto de sistema C4: tu sistema como una caja, usuarios y sistemas externos alrededor, flechas etiquetadas. La guía del diagrama de contexto de sistema explica qué va en él.

2. Objetivos de calidad

La mayoría de los documentos de arquitectura se saltan esta sección, y es la que explica todo lo demás. «Disponibilidad antes que consistencia» o «facilidad de cambio antes que rendimiento puro» le dice al lector por qué los contenedores tienen esa forma. Quédate en tres a cinco objetivos, ordénalos y dale a cada uno un escenario lo bastante concreto para probarlo: una cifra, una carga, un fallo.

3. Restricciones

Las restricciones son las decisiones que tomó otra persona: el equipo de plataforma, el departamento legal, la política de lenguajes de la empresa. Escribirlas pone fin a la conversación de «¿por qué no usasteis simplemente X?», y le dice a un futuro lector qué decisiones se pueden revisar y cuáles no.

4. Arquitectura: los diagramas C4

Es la sección que la mayoría considera «la arquitectura». Usa el modelo C4 porque da a cada diagrama una sola tarea:

• Diagrama de contenedores (nivel 2), siempre. Cada unidad desplegable y cada almacén de datos, cada uno con su tecnología, cada flecha con un protocolo. Si solo dibujas un diagrama, que sea este. La guía del diagrama de contenedores tiene un ejemplo completo.
• Diagramas de componentes (nivel 3), de forma selectiva. Solo para los contenedores con los que una persona nueva tendría problemas.
• Flujos clave. Dos o tres escenarios como pasos numerados. Un diagrama estático muestra que dos contenedores se comunican; un flujo muestra en qué orden y qué pasos espera el usuario. La guía del diagrama dinámico C4 muestra cómo escribir uno.

La tabla de contenedores con una columna Responsable está ahí a propósito. Un contenedor que no es de nadie es uno que nadie actualizará tampoco en este documento.

Si C4 es nuevo para ti, qué es el modelo C4 explica los cuatro niveles. Para ver ejemplos de estos diagramas aplicados a sistemas reales y grandes, consulta nuestros ejemplos de modelo C4.

5. Decisiones clave (ADR)

No escribas las decisiones dentro del texto. Guarda cada una como un architecture decision record en su propio archivo (contexto, decisión, alternativas consideradas, consecuencias) y deja aquí solo el índice. Los ADR se escriben una vez y se sustituyen en lugar de editarse, así el documento sigue siendo corto y el historial queda intacto. La guía completa de architecture decision records cubre el formato y cuándo una decisión merece uno.

Una buena prueba para el índice: una ingeniera nueva debería poder señalar cualquier caja sorprendente de la sección 4 y encontrar el ADR que la explica.

6. Aspectos transversales

Algunas cosas no viven en ningún contenedor concreto: la autenticación, el logging, la gestión de errores, dónde están los datos personales. Basta con una o dos líneas para cada una, con un enlace al detalle. En esta sección es donde un auditor pasa más tiempo, así que pónselo fácil.

7. Despliegue y operación

Sé breve y enlaza hacia fuera. Los entornos y en qué se diferencian, dónde se ejecuta el sistema, y enlaces a los runbooks y los dashboards. El detalle pertenece a tu código de infraestructura y a tus runbooks, que cambian más a menudo de lo que debería cambiar este documento.

8. Riesgos y deuda técnica

La sección honesta. Escribe lo que se sabe que es frágil, con un responsable y un plan, aunque el plan sea «aceptado, revisar en el T3». Un riesgo por escrito es un riesgo que alguien puede priorizar. Un riesgo que vive en la cabeza de una sola persona se va con ella.

9. Glosario

Todo sistema tiene palabras que aquí significan algo concreto: «pedido» frente a «carrito», «cuenta» frente a «tenant», «preparación». Define cada una una vez. Las personas nuevas leen esta sección más de lo que imaginas.

Cómo se relaciona con arc42

Si esta plantilla te resulta familiar, es porque es una versión reducida de las mismas ideas que arc42, la plantilla gratuita y de código abierto para documentar arquitectura creada por Peter Hruschka y Gernot Starke. arc42 tiene doce secciones y aconseja documentar «solo lo que necesitan tus stakeholders» (arc42 FAQ, B-1). La correspondencia:

Elige arc42 cuando necesites su estructura completa: entornos regulados, sistemas grandes con varios arquitectos o una organización que ya lo ha estandarizado. Elige algo de este tamaño cuando la alternativa sea no tener documento. Para una comparación detallada, incluido qué diagrama C4 va en cada sección de arc42, consulta arc42 vs C4.

Evitar que quede obsoleta

Todo documento de arquitectura es exacto el día en que se fusiona. Que lo siga siendo dentro de seis meses depende de unos pocos hábitos, la mayoría relacionados con los diagramas, porque las secciones 4 y 5 son donde la realidad cambia más rápido.

Guárdalo en el repositorio. docs/architecture.md junto al código significa que un pull request que divide un servicio puede actualizar la tabla de contenedores en la misma revisión. Una página de wiki no puede formar parte de una revisión de código.

Enlaza los diagramas, no pegues capturas. Una captura del diagrama de contenedores queda obsoleta en cuanto se renombra un contenedor. Un diagrama renderizado a partir de un modelo (DSL de Structurizr, un modelo YAML o una herramienta que lo contenga) solo está tan desactualizado como el modelo.

Haz que la fecha de revisión trabaje. Añade el documento a cualquier checklist que se ejecute cuando se añade o se quita un contenedor: la plantilla de pull request, la revisión de arquitectura, la planificación trimestral. «Próxima revisión: con cada cambio en las secciones 3 a 5» es una entrada válida.

Escribe las decisiones hacia delante. Nunca edites un ADR aceptado. Sustitúyelo. El índice de la sección 5 muestra entonces el historial, que es lo que la gente más necesita.

Comprueba automáticamente las partes estructurales. Las secciones 1 y 4 describen cosas que existen en el código: servicios, almacenes de datos, dependencias. Se pueden contrastar con el repositorio. Las secciones 2, 6 y 8 no, y necesitan a una persona, con una periodicidad. La guía de detección de deriva arquitectónica cubre los métodos para el primer tipo y qué puede ver y qué no cada uno.

Este es el problema para el que está hecho archyl, en la mitad del documento que corresponde a los diagramas. Conecta un repositorio y el descubrimiento por IA propone el modelo C4 (sistemas, contenedores, componentes y relaciones) para que lo revises y apruebes en lugar de dibujarlo. Los ADR, los docs y los flows se vinculan a los elementos que describen. Después, una puntuación de deriva comprueba si los elementos documentados siguen existiendo en el código, de forma determinista y sin IA en el proceso, de modo que una sección 4 obsoleta aparece como un número y no como una sorpresa. No comprueba tus objetivos de calidad ni tu lista de riesgos; esos siguen necesitando la fecha de revisión. Para las prácticas que mantienen la documentación al día con o sin herramienta, consulta documentación de arquitectura viva.

FAQ

¿Qué debe incluir un documento de arquitectura de software?

Como mínimo: el contexto y el alcance del sistema (usuarios y sistemas externos), un diagrama a nivel de contenedores con tecnologías, las decisiones de arquitectura clave con sus motivos, los riesgos conocidos y un responsable con una fecha de revisión. La plantilla de arriba añade objetivos de calidad, restricciones, aspectos transversales, notas de despliegue y un glosario, todo breve.

¿De verdad es gratis esta plantilla?

Sí. Es el bloque de Markdown de arriba. Cópialo y adáptalo a tu sistema. Sin registro, sin descarga, sin email.

¿Dónde debe estar el documento de arquitectura?

En el repositorio, como docs/architecture.md o ARCHITECTURE.md, junto a los ADR en docs/adr/. Así los cambios en la arquitectura y los cambios en el documento pasan por el mismo pull request.

¿Qué longitud debe tener un documento de arquitectura?

Tan corto como sea posible sin dejar de responder a las preguntas de sus lectores. Para un sistema de unos diez contenedores, unas pocas páginas es lo normal. Si crece mucho más, mueve el detalle a documentos enlazados (runbooks, ADR, referencias de API) y deja este como mapa.

¿Qué diferencia hay con un system design document?

Un system design document suele escribirse para un proyecto o una funcionalidad, antes de construirla, e incluye diseño detallado. Un documento de arquitectura describe el sistema completo tal como es ahora y cambia con él. Los equipos suelen tener un documento de arquitectura por sistema y muchos documentos de diseño a lo largo de su vida, y las decisiones duraderas de estos últimos acaban como ADR.

¿Debería usar arc42 en su lugar?

Si necesitas su estructura completa o tu organización ya lo usa, sí. Esta plantilla se corresponde con las secciones de arc42 (ver la tabla de arriba), así que puedes empezar aquí y pasar a arc42 más adelante sin reescribir nada.

¿Quieres que los diagramas de la sección 4 salgan de tu código y no de tu memoria? Prueba archyl gratis con el plan Developer, sin tarjeta de crédito. Sigue leyendo: arc42 vs C4 | Architecture Decision Records: la guía completa | ¿Qué es el modelo C4? | Documentación de arquitectura viva | Detección de deriva arquitectónica.