Acabamos de lanzar la funcionalidad que convierte la documentación de arquitectura en un ciudadano de primera clase de tu codebase. Conoce archyl.yaml — un DSL declarativo que describe tu modelo C4 completo, vive en Git, pasa por code review y se sincroniza automáticamente vía CI/CD.

Architecture as Code: Define tu modelo C4 completo en un archivo YAML

Los diagramas de arquitectura tienen un problema de caducidad. Los dibujas después de una sesión de diseño, se ven geniales durante una semana, y luego el código evoluciona mientras los diagramas se pudren. Seis meses después, el nuevo empleado mira fijamente un diagrama de Containers que muestra tres servicios que se fusionaron en el T2 y no menciona los dos que se construyeron en el T3.

Este problema nos obsesiona desde el primer día en Archyl. El descubrimiento por IA ayuda a mantener las cosas actualizadas. El editor visual hace que las actualizaciones sean indoloras. Pero hay una categoría de equipos — los que tratan la infraestructura como código, las políticas como código, todo como código — que querían algo más fundamental.

Querían que su arquitectura viviera en Git, junto al código que describe. Hoy, eso es exactamente lo que estamos lanzando.

¿Qué es `archyl.yaml`?

Es un único archivo YAML que describe de forma declarativa tu arquitectura completa. Colócalo en la raíz de tu repositorio y se convierte en la fuente de verdad de tu modelo C4 en Archyl.

Así es como se ve un archivo mínimo:

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

Eso es todo. Archyl lee este archivo, construye el modelo C4 completo, renderiza diagramas y mantiene todo sincronizado. Sin hacer clic en interfaces, sin sincronización manual, sin "olvidé actualizar el diagrama".

Todo en un solo archivo

El DSL no es un subconjunto simplificado — cubre todo el alcance de lo que Archyl puede modelar:

Los cuatro niveles C4. Los sistemas contienen containers, los containers contienen componentes, los componentes contienen elementos de código. El anidamiento YAML refleja la jerarquía directamente.

Relaciones con notación de puntos. Conecta cualquier par de elementos usando referencias legibles como Payment Service.API Gateway → Payment Service.Database. Sin UUIDs, sin identificadores crípticos. Compatible con grep, compatible con diffs, legible por humanos.

Tecnologías, entornos y releases. Define tu catálogo tecnológico, declara entornos de despliegue (staging, producción) y haz seguimiento de releases — todo desde el mismo archivo.

ADRs y documentación. Incluye tus Architecture Decision Records en línea o apunta a una carpeta en tu repositorio. Igual para la documentación del proyecto.

Contratos de API y canales de eventos. Declara tus especificaciones OpenAPI, definiciones gRPC, topics de Kafka, y vincúlalos a los componentes que los exponen o consumen.

Overlays visuales. Agrupa elementos en el diagrama con overlays nombrados, controlando colores y niveles.

Soporte para monorepos. Usa include para dividir tu arquitectura en múltiples archivos — uno por servicio, equipo o bounded context — y Archyl los fusiona automáticamente.

¿Por qué YAML?

Consideramos crear una sintaxis DSL personalizada (como el DSL de Structurizr o el HCL de Terraform). Elegimos YAML por razones prácticas:

Cero curva de aprendizaje. Todo desarrollador ya conoce YAML. No hay nueva sintaxis que aprender, ni parser que instalar, ni plugin de editor requerido.
Soporte IDE gratis. Publicamos un JSON Schema en /api/v1/dsl/schema. Apunta tu IDE y obtienes autocompletado, validación y documentación inline sin herramientas específicas de Archyl.
Compatible con diffs. Los diffs de YAML son limpios y legibles en pull requests. Los revisores ven inmediatamente "ah, agregaron un nuevo container al Payment Service y lo conectaron a Redis".
Ecosistema de herramientas. Linters, formateadores, motores de templates (Helm, Kustomize), todo funciona con YAML de forma nativa.

El workflow Git-nativo

Aquí es donde reside el verdadero poder. Porque archyl.yaml vive en tu repositorio, los cambios de arquitectura siguen el mismo workflow que los cambios de código:

Branch. Crea una rama feature, edita el YAML.
Review. Abre un pull request. Tu equipo revisa el cambio de arquitectura junto con el cambio de código.
Merge. Una vez aprobado, mergea a main.
Sync. Archyl detecta el cambio y actualiza los diagramas automáticamente.

Se acabó el "el diagrama dice X pero el código hace Y". Se acabaron los cambios de arquitectura que evitan la revisión. Se acabó la documentación que nadie sabe que fue actualizada.

Integración CI/CD

Construimos una integración de primera clase con pipelines CI/CD. Para GitHub, ofrecemos una GitHub Action oficial que se encarga de todo — leer el archivo, llamar a la API e informar qué cambió.

GitHub Actions (action oficial):

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

Eso es todo. Tres líneas de configuración y tu arquitectura se mantiene sincronizada en cada push. La action soporta rutas de archivos personalizadas (para monorepos), instancias Archyl autoalojadas, y expone outputs como summary, systems-created y relationships-created para pasos posteriores.

GitLab CI:

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

El endpoint /ingest acepta autenticación por API key, por lo que no se necesita flujo OAuth en CI. Importa el modelo completo, crea o actualiza cada elemento y devuelve un resumen detallado de lo que cambió.

También puedes sincronizar directamente desde la UI de Archyl. Si tu proyecto tiene un repositorio Git conectado, haz clic en "Sincronizar ahora" en la configuración de Architecture as Code y Archyl obtiene el archivo directamente desde tu repositorio.

Bidireccional: Export e Import

El workflow no es unidireccional. ¿Ya tienes un proyecto modelado en el editor visual de Archyl? Expórtalo:

Export genera un archyl.yaml completo a partir de tu modelo actual. Cada sistema, container, componente, relación, overlay, ADR, contrato de API, canal de eventos, release — todo serializado en YAML limpio.
Import parsea un archyl.yaml y crea o actualiza todos los elementos en tu proyecto. Es idempotente: importar el mismo archivo dos veces no crea duplicados. Los elementos se identifican por nombre y se actualizan.
Import as Project crea un proyecto completamente nuevo desde un archivo YAML. Coloca un archyl.yaml y obtén un proyecto completamente poblado con un clic.

Esto significa que puedes empezar en la UI, exportar a YAML, commitear en Git y cambiar al workflow code-first — o ir en sentido contrario. Sin lock-in en ninguno de los enfoques.

Resolución inteligente de referencias

Una de las partes más complicadas del DSL es resolver las referencias de elementos en relaciones, overlays, eventos y contratos de API. Construimos un resolver que maneja esto de forma natural:

Nombres cortos cuando no hay ambigüedad: API Gateway se resuelve directamente si solo un elemento tiene ese nombre.
Notación de puntos para desambiguar: Payment Service.API Gateway vs Analytics.API Gateway.
Cualquier profundidad funciona: System.Container.Component.CodeElement para referencias profundamente anidadas.

El resolver indexa cada elemento en cada profundidad de ruta posible, así que siempre usas la referencia no ambigua más corta. Los exports usan la misma lógica a la inversa — produciendo las referencias más legibles posibles.

Validación sin efectos secundarios

¿No estás seguro de que tu YAML es válido? El endpoint /validate (y el botón "Validar" en el modal de import) parsea y verifica tu archivo sin tocar la base de datos:

Verificación de versión del schema
Validación de campos obligatorios
Detección de nombres duplicados
Validación de tipos enumerados (tipos de containers, tipos de relaciones, etc.)
Resolución de referencias cruzadas

Los errores vuelven con rutas precisas (systems[2].containers[1].name) y mensajes claros. Intégralo en un hook pre-commit o un check de CI y detecta problemas antes de que lleguen a main.

Patrones del mundo real

El Monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

Cada servicio mantiene su propio archyl.yaml definiendo sus containers y componentes. El archivo raíz los fusiona, y las relaciones entre servicios se definen a nivel raíz. Las tecnologías y entornos se deduplican automáticamente.

El Bootstrapper

¿Empezando un nuevo proyecto? Crea un archyl.yaml antes de escribir código. Define los sistemas y containers que planeas construir. Usa "Import as Project" de Archyl para generar la arquitectura al instante. A medida que construyes, el YAML evoluciona con el código.

La pista de auditoría

Como el YAML está en Git, obtienes el historial completo gratis. git log archyl.yaml muestra cada cambio de arquitectura, quién lo hizo, cuándo, y el PR donde se discutió. Intenta conseguir eso con una herramienta de diagramas.

El generador de documentación

Exporta tu arquitectura a YAML y pásala por cualquier motor de templates para generar docs en Markdown, páginas de Confluence o wikis internas. El formato estructurado hace que la automatización sea trivial.

Qué viene después

Esta es la versión 1.0 del formato DSL. Esto es en lo que estamos trabajando:

Detección de drift. Comparar el YAML en tu repositorio con el modelo en producción y resaltar las diferencias — elementos agregados en la UI pero no en el archivo, o viceversa.

Comentarios de vista previa en PRs. Cuando un PR modifica archyl.yaml, un bot comenta con un diff visual de lo que cambió en la arquitectura.

Evolución del schema. A medida que agreguemos nuevas funcionalidades a Archyl, el DSL crecerá. Mantendremos compatibilidad hacia atrás y proporcionaremos herramientas de migración.

Pruébalo ahora

Architecture as Code está disponible hoy en todos los planes de Archyl. Si ya tienes un proyecto:

Ve a la página Architecture as Code en tu proyecto
Haz clic en Export para generar tu archyl.yaml
Commitéalo en tu repositorio
Agrega la GitHub Action oficial a tu workflow y listo

Si empiezas desde cero, crea un archyl.yaml, usa Import as Project, y tendrás una arquitectura C4 completamente renderizada en segundos.

Tu arquitectura merece el mismo rigor que tu código. Versiónala, revísala, automatízala.

¿Nuevo en C4? Empieza con nuestra Introducción al modelo C4. ¿Quieres que la IA genere la arquitectura inicial? Ver Descubrimiento de arquitectura con IA. ¿Ya usas asistentes de IA? Conéctalos a través de nuestro Servidor MCP.

Architecture as Code: Define tu modelo C4 completo en un archivo YAML - Archyl Blog