Arquitectura como Código

The whole model as code in the DSL editor

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: [...]
Campo Obligatorio Descripción
name Sí Nombre único del sistema
description No Qué hace este sistema
type No person, software_system o external_system
external No Si se trata de un sistema externo
tags No Tags de clasificación
technologies No Tecnologías utilizadas (hacen referencia al catálogo de tecnologías)
owners No Equipos y usuarios responsables
containers No Contenedores anidados (nivel 2 de C4)

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.

Un contenedor también puede declararse fuera de su sistema, en una lista containers de primer nivel, nombrando su sistema con parent_system. Así es como el archivo propio de un servicio lo describe en un monorepo (consulta la sección Include (soporte para monorepos) más abajo):

# 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.

Un componente también puede declararse fuera de su contenedor, en una lista components de primer nivel, nombrando su contenedor con parent_container: Sistema.Contenedor, o solo Contenedor cuando ningún otro sistema tiene un contenedor con ese nombre. Así cada módulo de un contenedor grande puede mantener su propio archivo junto a su código (consulta la sección Include (soporte para monorepos) más abajo):

# In web/lib/scoring/archyl.yaml
components:
  - name: FitScoring
    parent_container: Shop.Web
    description: Scores a job against a member profile
    technologies: [TypeScript]

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

Del mismo modo, un elemento de código puede declararse en una lista code de primer nivel, nombrando su componente con parent_component: Sistema.Contenedor.Componente, o Contenedor.Componente o Componente cuando ese nombre es único. El propio componente puede estar declarado en el primer nivel, en cualquiera de los archivos:

code:
  - name: scoreJob
    parent_component: Shop.Web.FitScoring
    type: function
    file: web/lib/scoring/score.ts

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)

Un monorepo puede mantener un archivo por servicio, o por módulo de un contenedor grande, junto a su código y un archyl.yaml raíz que los reúne:

# archyl.yaml
version: "1.0"
include:
  - services/payments/archyl.yaml
  - services/orders/archyl.yaml
systems:
  - name: Shop
    description: The online shop
# services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Shop
    type: api
    technologies: [Go]
relationships:
  - from: Payments API
    to: Stripe
    label: Charges cards
    type: calls
systems:
  - name: Stripe
    external: true

Cómo se combinan los archivos:

  • Las rutas son relativas al archivo que las declara y deben quedarse dentro del repositorio.
  • Un archivo incluido sigue el mismo esquema. No necesita version y puede incluir otros archivos; un archivo alcanzado dos veces se combina una sola vez.
  • Un elemento de una lista de primer nivel se une al padre que nombra, en cualquiera de los archivos y sea cual sea el orden de los includes: un contenedor de containers se une al sistema que nombra su parent_system, un componente de components al contenedor que nombra su parent_container, un elemento de code al componente que nombra su parent_component.
  • Un elemento declarado dos veces bajo el mismo padre detiene la importación (los nombres se comparan sin distinguir mayúsculas y minúsculas). También un nombre de padre corto que coincide con varios elementos: escribe su ruta completa.
  • Un sistema nombrado en varios archivos es un único sistema: sus contenedores se suman, y el primer archivo que da una descripción, un tipo, tecnologías, tags o propietarios los fija.
  • Las relaciones pueden referenciar elementos de cualquier archivo.
  • Los errores nombran el archivo del que proceden. Un include que falta, una ruta fuera del repositorio o un parent_system, parent_container o parent_component desconocido detienen la importación; no se escribe nada.
  • Se pueden incluir hasta 200 archivos.

Los include se resuelven allí donde se pueden leer los archivos:

Dónde Cómo
archyl dsl push / archyl dsl diff La CLI lee los archivos incluidos de tu árbol de trabajo y los envía con la raíz
Sincronizar ahora Archyl obtiene cada archivo incluido del repositorio
Subida de un zip Comprime en zip los archivos YAML del repositorio; el archyl.yaml menos profundo es la raíz
API REST Envía los archivos incluidos en files, indexados por ruta, y la ruta de la raíz en path (consulta la sección API REST)

Se rechaza pegar o subir un único archivo que tenga include, ya que faltarían los archivos que incluye.

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), junto con todos los archivos que alcanzan sus directivas include, y los importa. Los elementos que ya existen se actualizan y los nuevos se crean. Un campo que el archivo omite, como una descripción, conserva su valor en el modelo.

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

Entrada Obligatoria Valor por defecto Descripción
api-key Sí Clave API de Archyl con permiso de escritura
project-id Sí UUID del proyecto en Archyl
api-url No https://api.archyl.com URL base de la API (para instancias autoalojadas)
file No archyl.yaml Ruta del archivo YAML relativa a la raíz del repositorio

Salidas de la action

Salida Descripción
systems-created Número de sistemas creados
containers-created Número de contenedores creados
components-created Número de componentes creados
relationships-created Número de relaciones creadas
summary Resumen legible del resultado de la sincronización

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 .)}"

Cuando el archivo usa include, envía también los archivos que incluye, indexados por su ruta en el repositorio, y la ruta del propio archivo raíz:

{
  "content": "version: \"1.0\"\ninclude: [services/payments/archyl.yaml]\n...",
  "path": "archyl.yaml",
  "files": {
    "services/payments/archyl.yaml": "containers:\n  - name: Payments API\n..."
  }
}

archyl dsl push lo hace por ti. Los mismos campos funcionan en /dsl/diff y /dsl/validate.

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

Formato Ideal para
PNG Presentaciones, documentos, compartir por chat
SVG Herramientas de diseño, integración web, impresión
PDF Documentación formal, archivo

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:

Formato Tipo de archivo Herramienta de origen
Archyl YAML .yaml / .yml Formato nativo de Archyl
Structurizr DSL .dsl Structurizr
LikeC4 .c4 / .likec4 LikeC4
IcePanel JSON .json IcePanel
Backstage JSON .json Backstage

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.

Formato Nombre del proyecto Descripción del proyecto
Archyl YAML project.name — obligatorio project.description
Structurizr DSL El nombre del workspace — obligatorio La descripción del workspace
LikeC4 El primer elemento de nivel superior; si no, Imported LikeC4 Project No disponible
IcePanel JSON El objeto domain; si no, Imported IcePanel Project No disponible
Backstage JSON Siempre Imported Backstage Catalog No disponible

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:

Límite Valor
Tamaño del archivo comprimido 10 MiB
Archivos dentro del comprimido 500
Tamaño total descomprimido 50 MiB
Tamaño de un archivo 5 MiB (un archivo más grande se omite con una advertencia)
Anidamiento de includes 10 niveles

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