Architecture as Code: Define tu Diseño de Sistema de Forma Programática

Hay un patrón en la ingeniería de software que se repite cada pocos años. Una práctica que era manual y visual se codifica, se versiona y se automatiza -- y todo mejora.

Sucedió con la infraestructura. Pasamos de hacer clic en consolas de nube a escribir archivos Terraform. Sucedió con la configuración. Pasamos de editar archivos de configuración en servidores a declarar el estado deseado en manifiestos de Kubernetes. Sucedió con los esquemas de base de datos. Pasamos de ejecutar scripts SQL a mano a escribir archivos de migración.

Ahora está sucediendo con la documentación de arquitectura. Architecture as code es la práctica de definir tu diseño de sistema de forma programática -- en archivos de texto estructurados que pueden versionarse, revisarse, testearse y desplegarse a través de los mismos pipelines que tu código de aplicación.

Esta guía cubre todo lo que necesitas saber sobre architecture as code: qué es, por qué importa, cómo se compara con los enfoques solo visuales y cómo implementarlo en la práctica.

Qué Es Architecture as Code

Architecture as code (AaC) es la práctica de definir tu arquitectura de software en archivos de texto legibles por máquinas y escribibles por humanos. En lugar de dibujar cajas y flechas en una herramienta visual, describes tus sistemas, containers, componentes y sus relaciones en un formato estructurado como YAML, JSON o un DSL diseñado para tal fin.

Aquí tienes un ejemplo simple de una arquitectura definida en YAML:

version: "1.0"

project:
  name: "Payment Platform"
  description: "Handles all payment processing for the organization"

systems:
  - name: Payment Platform
    type: software_system
    description: "Core payment processing system"
    containers:
      - name: Payment API
        type: api
        description: "REST API for payment operations"
        technologies: [Go, gRPC, OpenAPI]
      - name: Payment Processor
        type: service
        description: "Processes payment transactions"
        technologies: [Go]
      - name: Transaction Database
        type: database
        description: "Stores transaction records"
        technologies: [PostgreSQL]
      - name: Payment Queue
        type: queue
        description: "Async payment processing queue"
        technologies: [Kafka]

  - name: Stripe
    type: external_system
    description: "Third-party payment gateway"

relationships:
  - from: Payment API
    to: Payment Processor
    label: "Forwards payment requests"
    type: uses
  - from: Payment Processor
    to: Transaction Database
    label: "Persists transactions"
    type: writes_to
  - from: Payment Processor
    to: Payment Queue
    label: "Publishes payment events"
    type: publishes_to
  - from: Payment Processor
    to: Stripe
    label: "Charges cards via"
    type: uses

Este archivo es la fuente única de verdad completa para la arquitectura. Una herramienta como Archyl lo lee, construye el modelo C4, renderiza diagramas interactivos y mantiene todo sincronizado. El archivo vive en tu repositorio Git, justo al lado del código que describe.

Por Qué los Enfoques Solo Visuales Se Quedan Cortos

Antes de architecture as code, los equipos típicamente documentaban su arquitectura usando herramientas visuales -- Lucidchart, draw.io, Miro o Figma. Estas herramientas son excelentes para sesiones de lluvia de ideas y diseño inicial, pero tienen limitaciones fundamentales como documentación a largo plazo:

Sin Control de Versiones

Los diagramas visuales se almacenan como archivos binarios o propietarios que no pueden compararse de forma significativa. Cuando alguien cambia un diagrama, puedes ver qué cambió, pero no puedes ver qué cambió. No hay un equivalente de git diff para un archivo de draw.io. No puedes revisar un cambio de diagrama en un pull request de la misma forma en que revisas un cambio de código.

Con architecture as code, cada cambio es un diff de texto. Agregar un nuevo servicio son unas pocas líneas de YAML. Renombrar un componente es un cambio de una sola línea. Los revisores pueden ver exactamente qué cambió, por qué cambió (desde el mensaje de commit) y aprobar o solicitar modificaciones.

Sin Automatización

Los diagramas visuales existen de forma aislada. No pueden disparar acciones, validar reglas ni integrarse con pipelines de CI/CD. Si tu diagrama dice que tienes 10 servicios pero tu cluster de Kubernetes ejecuta 12, nada detecta la discrepancia.

Architecture as code habilita la automatización. Puedes escribir reglas de validación que verifiquen tu definición de arquitectura contra tu infraestructura real. Puedes generar documentación desde el archivo de arquitectura. Puedes disparar alertas cuando el archivo de arquitectura diverge de la realidad.

Sin Colaboración a Escala

Cuando dos personas editan el mismo diagrama visual simultáneamente, los conflictos generalmente se resuelven con los cambios de una persona sobrescribiendo los de la otra. No hay una estrategia de merge para archivos visuales.

Con architecture as code, aplican los flujos de trabajo estándar de merge de Git. Dos equipos pueden modificar diferentes partes del archivo de arquitectura, y Git los fusiona limpiamente. Cuando ocurren conflictos, se resuelven de la misma manera que los conflictos de código -- a través de discusión y resolución intencional.

Sin Garantías de Consistencia

Un diagrama visual puede contener cualquier cosa. Las cajas pueden etiquetarse de forma inconsistente. Las flechas pueden significar cosas diferentes en diferentes partes del mismo diagrama. No hay esquema, no hay validación, no hay aplicación de convenciones de nomenclatura.

Los archivos de architecture as code tienen un esquema. Las herramientas validan el archivo en cada cambio. Si haces referencia a un container que no existe, la validación lo detecta. Si usas un tipo de relación invalido, se marca antes de que el cambio se fusione.

Dependencia del Proveedor y Portabilidad

Los diagramas visuales a menudo están atados a la herramienta que los creó. Migrar de Lucidchart a draw.io significa recrear manualmente cada diagrama. Migrar de una herramienta de architecture as code a otra es una conversión de formato -- automatizada y repetible.

Los Beneficios de Architecture as Code

Fuente Única de Verdad

Cuando tu arquitectura está definida en un solo archivo (o un conjunto de archivos), hay exactamente un lugar donde buscar. No hay duda sobre cuál diagrama es el actual, cuál página de Confluence tiene la última versión o si el PDF que alguien envío por email el mes pasado sigue siendo preciso.

Code Review para Cambios de Arquitectura

Este es quizá el beneficio más transformador. Cuando los cambios de arquitectura pasan por pull requests, reciben el mismo escrutinio que los cambios de código. Un arquitecto senior puede revisar una división de servicio propuesta antes de que suceda. El equipo puede discutir las implicaciones de una nueva dependencia antes de que se introduzca.

+ - name: Notification Service
+   type: service
+   description: "Handles email, SMS, and push notifications"
+   technologies: [Python, Celery, Redis]
+
+ - from: Order Service
+   to: Notification Service
+   label: "Triggers order notifications"
+   type: uses

Este diff cuenta una historia clara: alguien está agregando un Notification Service y conectándolo al Order Service. Los revisores pueden hacer preguntas, sugerir tecnologías alternativas o proponer límites de servicio diferentes -- todo antes de que se escriba una sola línea de código de aplicación.

El Historial de Git Es el Historial de la Arquitectura

Cada commit a tu archivo de arquitectura crea un registro permanente de como evoluciono la arquitectura. Puedes responder preguntas como:

  • ¿Cuándo se agregó el Search Service?
  • ¿Quién aprobó la migración de MySQL a PostgreSQL?
  • ¿Cómo se veía la arquitectura hace seis meses?
  • ¿Cómo ha crecido el número de servicios a lo largo del tiempo?

Este historial es invaluable para entender la evolución de tu sistema y para el onboarding de nuevos miembros del equipo.

Integración CI/CD

Architecture as code se integra naturalmente en los pipelines de integración continua y despliegue continuo. En cada pull request, puedes:

  • Validar el archivo de arquitectura contra su esquema
  • Verificar reglas de conformidad (por ejemplo, cada servicio debe tener un propietario documentado)
  • Generar diagramas actualizados
  • Detectar drift entre la arquitectura documentada y el sistema en ejecución
  • Publicar la arquitectura en tu plataforma de documentación

Esto hace de la documentación de arquitectura un artefacto vivo en lugar de un documento estático que se deteriora.

Refactorización y Automatización

Debido a que las definiciones de arquitectura son datos estructurados, puedes escribir scripts para manipularlos. ¿Necesitas renombrar un servicio en todas las relaciones? Un simple buscar-y-reemplazar en un archivo YAML. ¿Necesitas generar un reporte de todos los servicios que usan PostgreSQL? Parsea el YAML y filtra por tecnología. ¿Necesitas hacer cumplir una convención de nomenclatura? Escribe un linter.

Formatos y DSLs de Architecture as Code

Existen varios formatos y DSLs para definir architecture as code. Aquí tienes una descripción general de los enfoques más comunes.

Structurizr DSL

Creado por Simon Brown (el creador del modelo C4), Structurizr DSL es uno de los primeros formatos de architecture as code. Usa una sintaxis DSL personalizada:

workspace {
    model {
        user = person "User"
        softwareSystem = softwareSystem "My Software System" {
            webapp = container "Web Application" "Delivers content" "Java"
            database = container "Database" "Stores data" "PostgreSQL"
        }
        user -> webapp "Uses"
        webapp -> database "Reads from and writes to"
    }
    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }
    }
}

Structurizr fue pionero en el concepto de architecture as code para modelos C4. Sin embargo, su sintaxis DSL personalizada tiene una curva de aprendizaje y requiere herramientas específicas de Structurizr para renderizar.

Enfoques Basados en YAML

YAML se ha convertido en el estándar de facto para configuración declarativa en DevOps (Kubernetes, Docker Compose, GitHub Actions, dejando de lado Terraform HCL). Usar YAML para definiciones de arquitectura tiene la ventaja de la familiaridad -- la mayoría de los desarrolladores ya saben cómo leer y escribir YAML.

El formato archyl.yaml de Archyl toma este enfoque:

version: "1.0"

systems:
  - name: E-Commerce Platform
    type: software_system
    containers:
      - name: Web Frontend
        type: webapp
        technologies: [React, TypeScript, Next.js]
      - name: API Service
        type: api
        technologies: [Go, gRPC]
        components:
          - name: Auth Handler
            type: handler
            technologies: [JWT, OAuth2]
          - name: Product Handler
            type: handler
            technologies: [REST]
      - name: Product Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: Web Frontend
    to: API Service
    label: "Makes API calls to"
  - from: API Service
    to: Product Database
    label: "Reads/writes product data"

El anidamiento refleja directamente la jerarquía C4: los sistemas contienen containers, los containers contienen componentes. Las relaciones usan nombres legibles por humanos con notación de punto para desambiguacion. El formato es buscable con grep, comparable con diff y no requiere herramientas especializadas para leerlo.

JSON y Otros Formatos

Algunas herramientas usan JSON, TOML u otros formatos estructurados. El formato específico importa menos que los principios: la definición de arquitectura debe ser basada en texto, versionable y parseable por máquinas.

Implementando Architecture as Code: Un Flujo de Trabajo Práctico

Aquí tienes un flujo de trabajo paso a paso para adoptar architecture as code en tu equipo.

Paso 1: Comienza con lo que Existe

No intentes documentar toda tu arquitectura el primer día. Comienza con el diagrama de Container -- el panorama de servicios. Lista cada servicio desplegable, su stack tecnológico y las relaciones clave entre servicios.

Si usas Archyl, puedes crear el modelo visualmente en la UI y luego exportarlo como archyl.yaml, o escribir el archivo YAML desde cero. Ambos caminos te llevan al mismo resultado.

Paso 2: Haz Commit en tu Repositorio

Coloca el archivo de arquitectura en la raíz de tu repositorio principal (o en un repositorio de arquitectura dedicado si tu codebase está dividido en muchos repos). La ubicación importa menos que el principio: el archivo debe vivir en Git y pasar por code review.

my-platform/
  archyl.yaml        # Definicion de arquitectura
  src/
  docker-compose.yml
  .github/
    workflows/
      architecture.yml  # Pipeline de CI para arquitectura

Paso 3: Configura la Sincronización CI/CD

Configura tu pipeline de CI/CD para sincronizar el archivo de arquitectura con Archyl en cada merge a la rama principal. Esto asegura que los diagramas visuales y la documentación interactiva en Archyl siempre reflejen la última arquitectura committeada.

Un flujo de trabajo de GitHub Actions podría verse así:

name: Sync Architecture

on:
  push:
    branches: [main]
    paths: [archyl.yaml]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to Archyl
        run: |
          curl -X POST https://api.archyl.com/v1/sync \
            -H "Authorization: Bearer ${{ secrets.ARCHYL_TOKEN }}" \
            -H "Content-Type: application/yaml" \
            --data-binary @archyl.yaml

Paso 4: Haz los Cambios de Arquitectura a Través de Pull Requests

Desde este punto en adelante, los cambios de arquitectura siguen el mismo flujo de trabajo que los cambios de código:

  1. Crea una rama
  2. Modifica el archivo archyl.yaml
  3. Abre un pull request
  4. Obtén la revisión del equipo
  5. Fusiona a main
  6. CI/CD sincroniza el cambio a Archyl

Esto le da a los cambios de arquitectura la misma visibilidad, responsabilidad y trazabilidad que los cambios de código.

Paso 5: Agrega Reglas de Conformidad

A medida que tu práctica de architecture as code madura, agrega reglas de conformidad que validen la definición de arquitectura automáticamente. Ejemplos:

  • Cada container debe tener al menos una tecnología especificada
  • Cada sistema externo debe tener una descripción
  • No containers huérfanos (cada container debe tener al menos una relación)
  • Las convenciones de nomenclatura se siguen (por ejemplo, los servicios terminan en "Service")

El motor de reglas de conformidad de Archyl puede evaluar estas reglas automáticamente y reportar violaciones en el pipeline de CI o en el dashboard de Archyl.

Paso 6: Evoluciona la Definición con el Tiempo

Comienza con sistemas y containers. Agrega componentes cuando servicios específicos se vuelvan lo suficientemente complejos como para justificar documentación interna. Agrega ADRs a medida que tomes decisiones arquitectónicas importantes. Agrega contratos de API a medida que formalices los límites de servicio.

El archivo de arquitectura crece orgánicamente con tu sistema. No hay necesidad de cargar todos los detalles por adelantado.

Architecture as Code vs. Infrastructure as Code

Architecture as code e infrastructure as code (IaC) son prácticas complementarias pero distintas.

Infrastructure as code (Terraform, Pulumi, CloudFormation) define qué desplegar y cómo configurarlo. Es operacional: aprovisiona servidores, configura redes y gestiona recursos de nube.

Architecture as code define cómo se ve el sistema y cómo se relacionan sus partes. Es descriptivo: documenta la estructura conceptual, las elecciones tecnológicas y los límites de servicio.

La configuración ideal combina ambos:

  • Tus archivos Terraform definen la infraestructura
  • Tu archyl.yaml define la arquitectura
  • Las reglas de conformidad verifican que los dos se mantengan alineados

Cuando tu Terraform agrega un nuevo servicio pero el archivo de arquitectura no lo menciona, la detección de drift detecta la discrepancia.

Architecture as Code con Asistentes de IA

Una de las ventajas más convincentes de architecture as code es que los asistentes de IA pueden leerlo y razonar sobre él. Cuando tu arquitectura está definida en texto estructurado, herramientas como Claude Code y Cursor pueden:

  • Responder preguntas sobre tu arquitectura consultando el archivo YAML
  • Sugerir cambios de arquitectura basados en el estado actual
  • Generar código que respete la arquitectura documentada (por ejemplo, usando la base de datos correcta para el servicio correcto)
  • Detectar inconsistencias entre el código y la definición de arquitectura

Archyl va más allá con su servidor MCP. Los asistentes de IA no solo leen el archivo de arquitectura -- pueden consultar el modelo de arquitectura en vivo, recorrer relaciones e incluso proponer modificaciones. La arquitectura se convierte en una fuente de datos programable y consultable en lugar de un documento estático.

Errores Comunes

Sobre-ingeniar el Formato

No diseñes un DSL personalizado cuando YAML o un formato existente funciona. El objetivo es la adopción, y la adopción es más fácil cuando el formato es familiar. La mayoría de los desarrolladores ya conocen YAML por Docker Compose, Kubernetes y configuraciones de CI/CD.

Intentar Capturar Todo

Architecture as code debería capturar los aspectos estructurales de tu sistema: qué existe, cómo se conectan las cosas y qué tecnologías se usan. No intentes incrustar detalles operacionales (como políticas de escalado), configuraciones de runtime (como variables de entorno) o especificaciones de comportamiento (como formatos de respuesta de API) en el archivo de arquitectura.

No Hacer Cumplir el Flujo de Trabajo

Architecture as code solo funciona si los cambios pasan por el flujo de trabajo definido. Si la gente elude el archivo de arquitectura y hace cambios directamente en la herramienta visual, el archivo se vuelve obsoleto. Establece convenciones claras sobre cuál dirección es la autoritativa.

Ignorar la Salida Visual

Architecture as code no es un reemplazo para los diagramas visuales -- es una mejor manera de producirlos. El archivo de texto es la fuente de verdad, pero los diagramas renderizados son lo que la gente realmente mira día a día. Asegúrate de que la salida visual sea accesible, actualizada y fácil de navegar.

Cómo Empezar con Archyl

Archyl está diseñado desde cero para soportar architecture as code. La plataforma proporciona:

  • DSL basado en YAML que cubre el modelo C4 completo con sistemas, containers, componentes, relaciones y tecnologías
  • Sincronización bidireccional -- modela visualmente en la UI y exporta a YAML, o escribe YAML y sincroniza con la UI
  • Integración CI/CD para sincronización automatizada en cada commit
  • Reglas de conformidad que validan la definición de arquitectura contra tus estándares
  • Servidor MCP que hace la arquitectura consultable por asistentes de IA
  • Funciones de colaboración con code review, comentarios y propiedad por equipos

Ya sea que empieces desde cero o migres desde diagramas visuales, Archyl hace que architecture as code sea práctico para equipos de cualquier tamaño.

Comienza con architecture as code y aporta el mismo rigor a tu documentación de arquitectura que ya aportas a tu infraestructura y código de aplicación.