Arquitectura como Código

Archyl te permite definir toda tu arquitectura C4 en un único archivo YAML: archyl.yaml. Súbelo a tu repositorio, edítalo junto a tu código y deja que CI/CD mantenga tus diagramas sincronizados automáticamente.

Descripción general

El archivo archyl.yaml es una descripción declarativa de tu arquitectura. Admite:

• Los cuatro niveles C4 (sistemas, contenedores, componentes, código)
• Relaciones entre cualquier par de elementos
• Tecnologías, entornos y releases
• ADR, documentación, contratos API y canales de eventos
• Overlays visuales para agrupar elementos en el diagrama
• Soporte para monorepos mediante include

Puedes escribirlo a mano, exportarlo desde un proyecto existente o combinar ambos workflows.

Formato de archivo

Archyl busca el archivo DSL en la raíz del repositorio y prueba estos nombres en este orden:

1. archyl.yaml
2. .archyl.yaml
3. archyl.yml
4. .archyl.yml

Referencia del esquema

Estructura raíz

version: "1.0"

project:
  name: My Platform
  description: E-commerce platform serving 10M users
  tags: [e-commerce, saas]

technologies: [...]
environments: [...]
systems: [...]
relationships: [...]
overlays: [...]
events: [...]
api_contracts: [...]
adrs:
  folder: docs/adrs
  records: [...]
docs:
  folder: docs
  records: [...]
releases: [...]
include: [...]

Solo version es obligatorio. Todas las demás secciones son opcionales: incluye únicamente lo que necesites.

Sistemas (nivel 1 de C4)

Los sistemas son los elementos de nivel superior del modelo C4.

systems:
  - name: Payment Service
    description: Handles all payment processing
    type: software_system   # person | software_system | external_system
    external: false
    tags: [payments, critical]
    technologies: [Go, PostgreSQL]
    owners:
      teams: [backend-team]
      users: [vincent]
    containers: [...]

Contenedores (nivel 2 de C4)

Los contenedores se anidan dentro de su sistema padre.

systems:
  - name: Payment Service
    containers:
      - name: API Gateway
        description: REST API for payment operations
        type: api
        tags: [rest, public]
        technologies: [Go, Fiber]
        owners:
          teams: [backend-team]
        components: [...]

Tipos de contenedor disponibles: web_app, mobile_app, desktop_app, api, database, file_storage, message_queue, cache, service, function, worker, consumer, infrastructure, gateway, library.

Cuando uses include para los archivos de un monorepo, usa parent_system para indicar a qué sistema pertenece el contenedor:

# In services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Payment Service
    type: api

Componentes (nivel 3 de C4)

Los componentes se anidan dentro de su contenedor padre.

containers:
  - name: API Gateway
    components:
      - name: PaymentHandler
        description: HTTP handler for payment endpoints
        type: handler
        file: internal/handler/payment.go
        tags: [http]
        technologies: [Go]
        code: [...]

Tipos de componente disponibles: controller, service, repository, handler, middleware, model, util, config, adapter, port, resource, module, job, bundle, plugin, workflow, activity, entity.

Elementos de código (nivel 4 de C4)

Los elementos de código se anidan dentro de su componente padre.

components:
  - name: PaymentHandler
    code:
      - name: ProcessPayment
        description: Handles payment processing requests
        type: function
        language: go
        file: internal/handler/payment.go
        line_start: 42
        line_end: 87
        visibility: public
        signature: "func (h *PaymentHandler) ProcessPayment(c *fiber.Ctx) error"
        methods:
          - name: validate
            signature: "func validate(req PaymentRequest) error"
            return_type: error
            visibility: private
        properties:
          - name: maxRetries
            type: int
            visibility: private
            readonly: true

Tipos de elemento de código disponibles: class, interface, struct, function, method, enum, constant, type.

Relaciones

Las relaciones conectan dos elementos cualesquiera usando notación de puntos para las referencias anidadas.

relationships:
  - from: Payment Service.API Gateway
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL, PostgreSQL]
    tags: [data-access]
    style:
      color: "#6366f1"
      width: 2
      style: solid       # solid | dashed | dotted
      animated: false

Formato de la notación de puntos: System.Container.Component.CodeElement. Usa solo los niveles que necesites: Payment Service hace referencia al sistema y Payment Service.API Gateway, a un contenedor.

Tipos de relación disponibles: uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from.

Tecnologías

Define un catálogo de las tecnologías utilizadas en tu arquitectura.

technologies:
  - name: Go
    description: Primary backend language
    category: programming_language
    icon: go
  - name: PostgreSQL
    description: Main relational database
    category: database
    icon: postgresql

Categorías disponibles: programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.

Entornos

Define los entornos de despliegue de tus releases.

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"
  - name: Development
    color: "#6366f1"

Releases

Haz seguimiento de los despliegues versionados en cada entorno y elemento.

releases:
  - version: "2.4.0"
    status: deployed          # planned | in_progress | deployed | rolled_back | failed
    changelog: "Added payment retry logic and improved error handling"
    environment: Production
    container: Payment Service.API Gateway
    released_at: "2026-03-10T14:00:00Z"
    source: github_action
    source_url: "https://github.com/org/repo/actions/runs/12345"

Canales de eventos

Define la mensajería asíncrona entre servicios.

events:
  - name: PaymentCompleted
    description: Fired when a payment is successfully processed
    direction: produce         # produce | consume
    broker: kafka              # kafka | nats | sqs | rabbitmq | redis | pulsar | custom
    topic: payments.completed
    schema_format: json_schema # json_schema | avro | protobuf | text
    schema: |
      { "type": "object", "properties": { "paymentId": { "type": "string" } } }
    links:
      - Payment Service.API Gateway

Contratos API

Adjunta especificaciones de API a tu arquitectura.

api_contracts:
  - name: Payment API
    description: REST API for payment operations
    type: http                 # http | grpc | graphql | async
    version: "2.0"
    endpoint: /api/v2/payments
    file: docs/openapi.yaml    # path to spec file in repo
    links:
      - Payment Service.API Gateway

Puedes usar file para hacer referencia a un archivo de especificación del repositorio, o content para incluir la especificación directamente.

Registros de decisiones de arquitectura (ADR)

adrs:
  folder: docs/adrs            # optional: path to ADR folder in repo
  records:
    - title: Use event-driven architecture for payments
      number: 7
      status: accepted         # proposed | accepted | deprecated | superseded
      date: "2026-02-15"
      context: We need to decouple payment processing from order management
      decision: Use Kafka events for async communication between services
      consequences: Added complexity but improved resilience and scalability
      tags: [architecture, messaging]
      links:
        - Payment Service

Documentación

docs:
  folder: docs                 # optional: path to docs folder in repo
  records:
    - title: Payment Processing Guide
      file: docs/payments.md   # path to markdown file in repo
      tags: [payments, guide]
      links:
        - Payment Service.API Gateway

Puedes usar file para hacer referencia a un archivo markdown del repositorio, o content para incluir el contenido directamente.

Overlays

Agrupaciones visuales que aparecen en el diagrama.

overlays:
  - name: Payment Domain
    description: All payment-related services
    color: "#6366f1"
    level: 2                   # C4 level (1=system, 2=container, 3=component, 4=code)
    elements:
      - Payment Service.API Gateway
      - Payment Service.Database
      - Payment Service.Worker

Include (soporte para monorepos)

En los monorepos, reparte tu arquitectura en varios archivos y combínalos:

include:
  - services/payments/archyl.yaml
  - services/orders/archyl.yaml
  - services/users/archyl.yaml

Cada archivo incluido sigue el mismo esquema. Usa parent_system en los contenedores para indicar a qué sistema pertenecen cuando se definen en un archivo aparte.

Ejemplo completo

version: "1.0"

project:
  name: E-Commerce Platform
  description: Online marketplace with payment processing
  tags: [e-commerce, saas, marketplace]

technologies:
  - name: Go
    category: programming_language
  - name: React
    category: framework
  - name: PostgreSQL
    category: database
  - name: Kafka
    category: message_broker
  - name: Redis
    category: cache

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"

systems:
  - name: Storefront
    description: Customer-facing web application
    type: software_system
    technologies: [React]
    containers:
      - name: Web App
        type: web_app
        technologies: [React]
      - name: BFF
        description: Backend for frontend
        type: api
        technologies: [Go]

  - name: Payment Service
    description: Handles payment processing
    type: software_system
    technologies: [Go, PostgreSQL]
    containers:
      - name: API
        type: api
        technologies: [Go]
        components:
          - name: PaymentHandler
            type: handler
          - name: PaymentService
            type: service
          - name: PaymentRepository
            type: repository
      - name: Database
        type: database
        technologies: [PostgreSQL]
      - name: Worker
        type: worker
        technologies: [Go]

  - name: Stripe
    description: Third-party payment processor
    type: external_system
    external: true

relationships:
  - from: Storefront.Web App
    to: Storefront.BFF
    label: API calls
    type: uses
    technologies: [HTTPS]
  - from: Storefront.BFF
    to: Payment Service.API
    label: Process payments
    type: calls
    technologies: [gRPC]
  - from: Payment Service.API
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL]
  - from: Payment Service.API
    to: Stripe
    label: Process charges
    type: calls
    technologies: [HTTPS]
  - from: Payment Service.Worker
    to: Payment Service.Database
    label: Polls for pending payments
    type: reads_from

events:
  - name: PaymentCompleted
    broker: kafka
    topic: payments.completed
    direction: produce
    links:
      - Payment Service.API

overlays:
  - name: Payment Domain
    level: 2
    color: "#6366f1"
    elements:
      - Payment Service.API
      - Payment Service.Database
      - Payment Service.Worker

releases:
  - version: "1.2.0"
    status: deployed
    environment: Production
    container: Payment Service.API
    changelog: Added retry logic for failed charges
    released_at: "2026-03-01T10:00:00Z"

Sincronizar desde un repositorio

Si tu repositorio contiene un archyl.yaml, puedes sincronizarlo directamente desde la interfaz de Archyl:

1. Ve a Configuración del Proyecto > Arquitectura como Código
2. Haz clic en Sincronizar ahora

Archyl obtiene el archivo de la rama por defecto de tu repositorio (o de la rama configurada en los ajustes del DSL) y lo importa. Los elementos que ya existen se actualizan y los nuevos se crean.

Integración con CI/CD

GitHub Action (oficial)

La GitHub Action oficial archyl-com/actions/sync es la forma más sencilla de mantener tu arquitectura sincronizada. Lee tu archyl.yaml, lo envía a la API de Archyl e informa de lo que se ha creado o actualizado.

Configuración mínima:

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'

Con salida de resumen:

- uses: archyl-com/actions/sync@v1
  id: sync
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
- run: echo "${{ steps.sync.outputs.summary }}"

Ruta de archivo personalizada (monorepo):

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
    file: 'services/payments/archyl.yaml'

Archyl autoalojado:

- uses: archyl-com/actions/sync@v1
  with:
    api-url: 'https://archyl.your-company.com'
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'

Entradas de la action

Salidas de la action

GitLab CI/CD

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

API REST

Puedes enviar contenido DSL desde cualquier sistema de CI/CD o script:

curl -X POST https://your-instance.com/api/v1/projects/{projectId}/dsl/ingest \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"

El endpoint de ingesta devuelve un resumen de lo que se ha creado:

{
  "source": "api",
  "import": {
    "systemsCreated": 2,
    "containersCreated": 5,
    "componentsCreated": 12,
    "codeElementsCreated": 0,
    "relationshipsCreated": 8,
    "overlaysCreated": 1,
    "technologiesCreated": 4,
    "adrsCreated": 0,
    "docsCreated": 0,
    "eventsCreated": 1,
    "apiContractsCreated": 0,
    "environmentsCreated": 2,
    "releasesCreated": 1
  }
}

Exportar a YAML

Puedes exportar cualquier proyecto existente como archivo archyl.yaml:

1. Abre tu proyecto
2. Haz clic en Exportar en la barra de herramientas
3. Selecciona YAML (Arquitectura como Código)

Esto genera un archyl.yaml completo que puedes subir a tu repositorio. Es una excelente manera de crear el archivo a partir de un proyecto existente o de una arquitectura descubierta con IA.

También puedes exportarlo mediante la API:

curl -H "X-API-Key: your-api-key" \
  https://your-instance.com/api/v1/projects/{projectId}/dsl/export \
  -o archyl.yaml

JSON Schema para soporte en el IDE

Archyl ofrece un JSON Schema para los archivos archyl.yaml, de modo que tu editor pueda ofrecer autocompletado y validación. El esquema está disponible en:

https://your-instance.com/api/v1/dsl/schema

VS Code

Añade esto a tu archyl.yaml para activar la validación del esquema:

# yaml-language-server: $schema=https://your-instance.com/api/v1/dsl/schema
version: "1.0"

O configúralo de forma global en los ajustes de VS Code:

{
  "yaml.schemas": {
    "https://your-instance.com/api/v1/dsl/schema": ["archyl.yaml", ".archyl.yaml"]
  }
}

Exportación de imágenes y PDF

Archyl también permite exportar tus diagramas como imágenes para presentaciones y documentos.

Formatos disponibles

Cómo exportar

1. Navega al nivel C4 que quieres exportar
2. Haz clic en Exportar en la barra de herramientas
3. Selecciona tu formato (PNG, SVG o PDF)
4. Configura las opciones (fondo, calidad, área de visualización)
5. Haz clic en Exportar

Marca Exportar todos los niveles para generar un archivo independiente por cada nivel C4.

Opciones de exportación

• Fondo: incluye el fondo oscuro del lienzo o usa un fondo transparente
• Calidad (solo PNG): resolución Estándar, Alta o Impresión
• Área de visualización: ajustar al contenido, incluir márgenes o exportar la vista actual

Importar proyectos

Puedes crear un nuevo proyecto importándolo desde varios formatos. Archyl admite cinco fuentes de importación:

Cómo importar

1. Desde tu lista de proyectos, haz clic en Importar proyecto
2. Selecciona la pestaña del formato de origen (Archyl YAML, Structurizr DSL, LikeC4, IcePanel o Backstage)
3. Sube el archivo o pega su contenido
4. Haz clic en Validar para previsualizar lo que se creará
5. Haz clic en Crear proyecto

Todo el proceso lleva menos de un minuto. Todos los sistemas, contenedores, componentes, relaciones, tecnologías y tags se importan automáticamente.

Nombre y descripción del proyecto

Crear un proyecto requiere un nombre, y cada formato lo lleva en un lugar distinto. La falta de nombre es la causa más frecuente de una importación rechazada.

Solo Archyl YAML y Structurizr DSL pueden fallar esta comprobación. Los demás formatos siempre recurren a un nombre generado que puedes cambiar después de importar.

En Structurizr, el nombre y la descripción son las dos cadenas opcionales del encabezado workspace:

workspace "My Platform" "Microservices architecture" {
    model {
        user = person "User"
        platform = softwareSystem "My Platform" {
            api = container "API" "REST API" "Go"
        }
        user -> api "Uses"
    }
}

Un workspace { ... } sin nombre se analiza correctamente, pero no puede crear un proyecto: Archyl lo rechaza y te pide que le pongas nombre al workspace. Importar en un proyecto existente no tiene ese requisito: ahí el nombre del workspace se ignora, porque el proyecto ya tiene uno.

Importación de Structurizr DSL

Archyl analiza los archivos de workspace .dsl de Structurizr y extrae el modelo C4 completo:

• Elementos person, softwareSystem, container y component
• Todas las relaciones -> con sus descripciones y tecnologías
• Detección de sistemas externos a partir de los tags
• Extracción de tecnologías a partir de los argumentos posicionales
• Grupos convertidos en tags

Las vistas, los estilos, los temas y los nodos de despliegue se omiten (Archyl tiene su propia capa visual).

El nombre y la descripción del workspace se convierten en el nombre y la descripción del proyecto — consulta la sección Nombre y descripción del proyecto más arriba. Un workspace sin nombre puede importarse en un proyecto existente, pero no puede crear uno.

Workspaces repartidos en varios archivos (!include)

Un workspace repartido en varios archivos — !include systems/payments.dsl y similares — no puede importarse como un único archivo, porque los archivos incluidos no están ahí para resolverse. En su lugar, sube todo el workspace como un .zip en la pestaña Structurizr DSL: los archivos del comprimido se descomprimen y cada !include se resuelve contra ellos.

• El punto de entrada es workspace.dsl si el archivo comprimido lo contiene; si no, el .dsl menos profundo. Archyl indica qué archivo ha usado.
• Las rutas se resuelven de forma relativa al archivo que hace la inclusión, así que los includes anidados funcionan.
• Incluir un directorio incorpora todos los .dsl que hay directamente dentro, por orden de nombre.
• Los ciclos de inclusión se rompen y se notifican en lugar de hacer fallar la importación.
• Los destinos remotos (!include https://…) se rechazan, y las rutas que salen del archivo comprimido se omiten.

Todo lo que no pueda resolverse se convierte en una advertencia en el resultado de la importación: el resto del workspace se importa igualmente.

Límites del archivo comprimido:

Solo se conservan los archivos .dsl, .md, .json, .yaml, .yml y .txt; todo lo demás del archivo comprimido se ignora.

A través de la API, envía el archivo comprimido como multipart form data en un campo file, con un campo entry opcional que indica el punto de entrada: POST /api/v1/dsl/validate-archive lo valida, POST /api/v1/projects/{id}/dsl/import-archive lo importa en un proyecto y POST /api/v1/dsl/import-project-archive crea un proyecto a partir de él. La herramienta MCP import_dsl y la sincronización del repositorio leen un único archivo y no resuelven !include.

Importación de LikeC4

Archyl es la primera herramienta que importa archivos LikeC4. El importador gestiona las particularidades de LikeC4:

• Tipos de elemento personalizados de los bloques specification, asignados a niveles C4
• Jerarquías de elementos anidados resueltas en sistemas, contenedores y componentes
• Propiedades technology: y description: (con o sin la sintaxis de dos puntos)
• Tags #hashtag convertidos en tags estándar
• Detección del tag #external para clasificar los límites del sistema
• Varios bloques model combinados automáticamente
• Compatibilidad con cadenas entre comillas simples y entre comillas triples

Importación de IcePanel JSON

El formato de exportación JSON de IcePanel es totalmente compatible:

• Tipos de objeto system, actor, app, store y component asignados a elementos C4
• Campo external: true para clasificar sistemas externos
• modelConnections convertidas en relaciones
• tagIds resueltos en nombres de tag a partir del array tags
• Objetos domain usados como nombre del proyecto

Importación de Backstage

Archyl importa el JSON del Software Catalog que devuelve el endpoint /api/catalog/entities de Backstage:

• Las entidades System se convierten en sistemas de Archyl (las colisiones entre namespaces se desambiguan automáticamente)
• Las entidades Component y Resource se agrupan como contenedores bajo su sistema propietario (mediante spec.system o la relación partOf)
• Los Components/Resources sin sistema padre se agrupan bajo un sistema sintético Uncategorized
• Los tipos de Resource se asignan a tipos de contenedor de Archyl: s3-bucket → file_storage; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database; kafka-topic, sqs-queue → message_queue; repository → library; todo lo demás → infrastructure
• Tipos de Component asignados: service → service, cronworkflow → worker, website → web_app, library → library
• Las entidades API se importan como Contratos API, conservando como contenido la spec.definition inline (OpenAPI / gRPC / GraphQL / AsyncAPI) y enlazadas a los componentes proveedores y consumidores
• dependsOn, consumesApi, producesTo, consumesFrom, versionedIn (y sus inversas) se traducen en relaciones de Archyl
• metadata.namespace, spec.lifecycle y spec.type se exponen como tags
• Las entidades User y Group se omiten: el grafo de personas y equipos de Backstage no es un concepto de C4

Para exportar tu catálogo:

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

Después, suelta entities.json en la pestaña Backstage del diálogo de importación. Las listas de recursos de catálogos grandes pueden generar miles de contenedores: revisa el resultado y elimina lo que no necesites.

Importación vía MCP (agentes de IA)

La misma capacidad de importación está disponible a través de la herramienta MCP import_dsl:

Use the import_dsl tool with:
- projectId: your project UUID
- content: the DSL/JSON content
- format: "archyl", "structurizr", "likec4", "icepanel", or "backstage"

Esto permite a los agentes de programación con IA (Claude Code, Cursor, Windsurf) importar archivos de arquitectura de forma programática.

Importar en proyectos existentes

También puedes importar en un proyecto existente (no solo crear proyectos nuevos):

1. Abre tu proyecto
2. Ve a Arquitectura como Código
3. Haz clic en Importar
4. Selecciona el formato y sube el archivo

Los elementos que ya existen se actualizan y los nuevos se crean.

Próximos pasos

• Visión general de la API — Referencia completa de la API para los endpoints DSL
• Compartir e integrar — Comparte diagramas en vivo
• Gestión de releases — Haz seguimiento de los despliegues en tu YAML
• Notificaciones por webhook — Recibe avisos cuando cambie la arquitectura