Architecture as code aporta el mismo rigor que infrastructure as code trajo a las operaciones. Esta guia cubre que es AaC, por que supera los enfoques solo visuales, ejemplos reales en YAML y DSL, flujos de trabajo con control de versiones, integracion CI/CD y como Archyl lo hace practico.

Architecture as Code: Define tu Diseno de Sistema de Forma Programatica

Hay un patron en la ingenieria de software que se repite cada pocos anos. Una practica que era manual y visual se codifica, se versiona y se automatiza -- y todo mejora.

Sucedio con la infraestructura. Pasamos de hacer clic en consolas de nube a escribir archivos Terraform. Sucedio con la configuracion. Pasamos de editar archivos de configuracion en servidores a declarar el estado deseado en manifiestos de Kubernetes. Sucedio con los esquemas de base de datos. Pasamos de ejecutar scripts SQL a mano a escribir archivos de migracion.

Ahora esta sucediendo con la documentacion de arquitectura. Architecture as code es la practica de definir tu diseno de sistema de forma programatica -- en archivos de texto estructurados que pueden versionarse, revisarse, testearse y desplegarse a traves de los mismos pipelines que tu codigo de aplicacion.

Esta guia cubre todo lo que necesitas saber sobre architecture as code: que es, por que importa, como se compara con los enfoques solo visuales y como implementarlo en la practica.

Que Es Architecture as Code

Architecture as code (AaC) es la practica de definir tu arquitectura de software en archivos de texto legibles por maquinas 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 disenado para tal fin.

Aqui 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 unica 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 codigo que describe.

Por Que los Enfoques Solo Visuales Se Quedan Cortos

Antes de architecture as code, los equipos tipicamente documentaban su arquitectura usando herramientas visuales -- Lucidchart, draw.io, Miro o Figma. Estas herramientas son excelentes para sesiones de lluvia de ideas y diseno inicial, pero tienen limitaciones fundamentales como documentacion 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 que cambio, pero no puedes ver que cambio. 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 codigo.

Con architecture as code, cada cambio es un diff de texto. Agregar un nuevo servicio son unas pocas lineas de YAML. Renombrar un componente es un cambio de una sola linea. Los revisores pueden ver exactamente que cambio, por que cambio (desde el mensaje de commit) y aprobar o solicitar modificaciones.

Sin Automatizacion

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 automatizacion. Puedes escribir reglas de validacion que verifiquen tu definicion de arquitectura contra tu infraestructura real. Puedes generar documentacion desde el archivo de arquitectura. Puedes disparar alertas cuando el archivo de arquitectura diverge de la realidad.

Sin Colaboracion a Escala

Cuando dos personas editan el mismo diagrama visual simultaneamente, 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 estandar 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 codigo -- a traves de discusion y resolucion intencional.

Sin Garantias 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 validacion, no hay aplicacion 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 validacion lo detecta. Si usas un tipo de relacion invalido, se marca antes de que el cambio se fusione.

Dependencia del Proveedor y Portabilidad

Los diagramas visuales a menudo estan atados a la herramienta que los creo. Migrar de Lucidchart a draw.io significa recrear manualmente cada diagrama. Migrar de una herramienta de architecture as code a otra es una conversion de formato -- automatizada y repetible.

Los Beneficios de Architecture as Code

Fuente Unica de Verdad

Cuando tu arquitectura esta definida en un solo archivo (o un conjunto de archivos), hay exactamente un lugar donde buscar. No hay duda sobre cual diagrama es el actual, cual pagina de Confluence tiene la ultima version o si el PDF que alguien envio por email el mes pasado sigue siendo preciso.

Code Review para Cambios de Arquitectura

Este es quiza el beneficio mas transformador. Cuando los cambios de arquitectura pasan por pull requests, reciben el mismo escrutinio que los cambios de codigo. Un arquitecto senior puede revisar una division 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 esta agregando un Notification Service y conectandolo al Order Service. Los revisores pueden hacer preguntas, sugerir tecnologias alternativas o proponer limites de servicio diferentes -- todo antes de que se escriba una sola linea de codigo de aplicacion.

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:

¿Cuando se agrego el Search Service?
¿Quien aprobo la migracion de MySQL a PostgreSQL?
¿Como se veia la arquitectura hace seis meses?
¿Como ha crecido el numero de servicios a lo largo del tiempo?

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

Integracion CI/CD

Architecture as code se integra naturalmente en los pipelines de integracion 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 ejecucion
Publicar la arquitectura en tu plataforma de documentacion

Esto hace de la documentacion de arquitectura un artefacto vivo en lugar de un documento estatico que se deteriora.

Refactorizacion y Automatizacion

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 tecnologia. ¿Necesitas hacer cumplir una convencion de nomenclatura? Escribe un linter.

Formatos y DSLs de Architecture as Code

Existen varios formatos y DSLs para definir architecture as code. Aqui tienes una descripcion general de los enfoques mas 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 especificas de Structurizr para renderizar.

Enfoques Basados en YAML

YAML se ha convertido en el estandar de facto para configuracion 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 mayoria de los desarrolladores ya saben como 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 jerarquia C4: los sistemas contienen containers, los containers contienen componentes. Las relaciones usan nombres legibles por humanos con notacion 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 especifico importa menos que los principios: la definicion de arquitectura debe ser basada en texto, versionable y parseable por maquinas.

Implementando Architecture as Code: Un Flujo de Trabajo Practico

Aqui 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 dia. Comienza con el diagrama de Container -- el panorama de servicios. Lista cada servicio desplegable, su stack tecnologico 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 raiz de tu repositorio principal (o en un repositorio de arquitectura dedicado si tu codebase esta dividido en muchos repos). La ubicacion 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 Sincronizacion 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 documentacion interactiva en Archyl siempre reflejen la ultima arquitectura committeada.

Un flujo de trabajo de GitHub Actions podria verse asi:

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 Traves de Pull Requests

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

Crea una rama
Modifica el archivo archyl.yaml
Abre un pull request
Obten la revision del equipo
Fusiona a main
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 codigo.

Paso 5: Agrega Reglas de Conformidad

A medida que tu practica de architecture as code madura, agrega reglas de conformidad que validen la definicion de arquitectura automaticamente. Ejemplos:

Cada container debe tener al menos una tecnologia especificada
Cada sistema externo debe tener una descripcion
No containers huerfanos (cada container debe tener al menos una relacion)
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 automaticamente y reportar violaciones en el pipeline de CI o en el dashboard de Archyl.

Paso 6: Evoluciona la Definicion con el Tiempo

Comienza con sistemas y containers. Agrega componentes cuando servicios especificos se vuelvan lo suficientemente complejos como para justificar documentacion interna. Agrega ADRs a medida que tomes decisiones arquitectonicas importantes. Agrega contratos de API a medida que formalices los limites de servicio.

El archivo de arquitectura crece organicamente 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 practicas complementarias pero distintas.

Infrastructure as code (Terraform, Pulumi, CloudFormation) define que desplegar y como configurarlo. Es operacional: aprovisiona servidores, configura redes y gestiona recursos de nube.

Architecture as code define como se ve el sistema y como se relacionan sus partes. Es descriptivo: documenta la estructura conceptual, las elecciones tecnologicas y los limites de servicio.

La configuracion 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 deteccion de drift detecta la discrepancia.

Architecture as Code con Asistentes de IA

Una de las ventajas mas convincentes de architecture as code es que los asistentes de IA pueden leerlo y razonar sobre el. Cuando tu arquitectura esta 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 codigo que respete la arquitectura documentada (por ejemplo, usando la base de datos correcta para el servicio correcto)
Detectar inconsistencias entre el codigo y la definicion de arquitectura

Archyl va mas alla 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 estatico.

Errores Comunes

Sobre-ingeniar el Formato

No disenes un DSL personalizado cuando YAML o un formato existente funciona. El objetivo es la adopcion, y la adopcion es mas facil cuando el formato es familiar. La mayoria de los desarrolladores ya conocen YAML por Docker Compose, Kubernetes y configuraciones de CI/CD.

Intentar Capturar Todo

Architecture as code deberia capturar los aspectos estructurales de tu sistema: que existe, como se conectan las cosas y que tecnologias se usan. No intentes incrustar detalles operacionales (como politicas 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 cual direccion 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 dia a dia. Asegurate de que la salida visual sea accesible, actualizada y facil de navegar.

Como Empezar con Archyl

Archyl esta disenado 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 tecnologias
Sincronizacion bidireccional -- modela visualmente en la UI y exporta a YAML, o escribe YAML y sincroniza con la UI
Integracion CI/CD para sincronizacion automatizada en cada commit
Reglas de conformidad que validan la definicion de arquitectura contra tus estandares
Servidor MCP que hace la arquitectura consultable por asistentes de IA
Funciones de colaboracion 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 practico para equipos de cualquier tamano.

Comienza con architecture as code y aporta el mismo rigor a tu documentacion de arquitectura que ya aportas a tu infraestructura y codigo de aplicacion.

Architecture as Code: Define tu Diseno de Sistema de Forma Programatica - Archyl Blog