Elige cómo empezar

Un proyecto de Archyl contiene un modelo C4 de tu software: sistemas, contenedores, componentes y código, y las relaciones entre ellos. Hay cuatro formas de rellenarlo. Se pueden combinar, y ninguna te ata.

Camino	Mejor cuando	Necesitas	Primer modelo en
Dibujarla en la aplicación	Estás explorando, o el sistema aún no está construido	Un navegador	Minutos para un diagrama de contexto
Descubrirla con IA	El código existe y quieres un primer borrador rápido	Un repositorio conectado y el descubrimiento con IA en tu plan	Unos minutos, y luego una revisión
Escribirla como código	Quieres revisar el modelo en pull requests y versionarlo con el código, o prefieres no enviar código a una IA	La CLI `archyl` y un editor de texto	Lo que tardes en escribir el archivo
Importarla	Ya modelas en Structurizr, LikeC4, IcePanel o Backstage	Una exportación de esa herramienta	Menos de un minuto

Elijas lo que elijas, los siguientes pasos son los mismos: conectar tus agentes de codificación y mantener el modelo al día con el código.

Dibújala en la aplicación

Crea un proyecto desde el panel y añade sistemas, contenedores y relaciones en el lienzo. La Guía de Inicio Rápido lo explica paso a paso.

Dibujar es el punto de partida adecuado para un sistema que aún no existe, o para esbozar el contexto antes de escribir código. Puedes pasarte al código más adelante: archyl dsl pull escribe lo que dibujaste en archyl.yaml.

Descúbrela con IA

El descubrimiento con IA lee un repositorio conectado y propone sistemas, contenedores, componentes, relaciones y tecnologías. Nada entra en el modelo hasta que lo apruebas.

Desde la aplicación: conecta el repositorio en Configuración del Proyecto › Integración Git (consulta Integración Git), lanza un descubrimiento y revisa lo que ha encontrado.

Desde el terminal, en la raíz del repositorio:

archyl login
archyl init --new

init --new crea el proyecto, conecta el repositorio a partir de su remote de git, ejecuta el descubrimiento mientras lo sigues, abre la revisión, dibuja el resultado y ofrece conectar tus agentes de codificación. Flags útiles: --name, --team, --branch, --provider para un remote autoalojado (github_enterprise, gitlab_private, gitea) y --yes para aceptar todos los valores por defecto. Consulta la guía de la CLI.

El descubrimiento funciona con monorepos: reconoce apps/, packages/, services/ y libs/, y asigna cada servicio a un contenedor.

Escríbela como código

Describe la arquitectura en un archyl.yaml en la raíz del repositorio y súbelo con push. El formato del archivo está en Arquitectura como Código.

archyl login
archyl init --new --no-discover   # create the project and link this repository, no AI
$EDITOR archyl.yaml               # describe the architecture
archyl dsl diff                   # what a push would create or change
archyl dsl push                   # import it
archyl diagram                    # look at the result

Un archivo mínimo:

version: "1.0"
systems:
  - name: Shop
    containers:
      - name: Storefront
        type: web_app
        technologies: [React]
      - name: Orders API
        type: api
        technologies: [Go]
      - name: Orders DB
        type: database
        technologies: [PostgreSQL]
  - name: Stripe
    external: true
relationships:
  - from: Storefront
    to: Orders API
    label: Places orders
    type: calls
  - from: Orders API
    to: Orders DB
    type: reads_from
  - from: Orders API
    to: Stripe
    label: Charges cards
    type: calls

Los elementos se emparejan por nombre. Un push crea lo nuevo y actualiza lo que cambió, y nunca borra nada: un elemento que solo tiene Archyl se queda, y archyl dsl diff lo lista como «only in Archyl».

Tu agente de codificación puede escribir la primera versión: ejecuta archyl setup y pídele que describa el repositorio en archyl.yaml siguiendo el esquema. Sigue siendo tu archivo y te toca revisarlo.

Para mantener sincronizados el archivo y el modelo, haz commit de archyl.yaml y haz push desde CI con la GitHub Action, o usa Sincronizar ahora en Configuración del Proyecto › Arquitectura como Código. archyl dsl diff --exit-code hace fallar un job de CI cuando difieren.

Impórtala desde otra herramienta

Desde la lista de proyectos, haz clic en Importar proyecto y elige el formato: Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON o Backstage JSON. Un workspace de Structurizr repartido en archivos !include se puede subir como zip. Los detalles, y dónde guarda cada formato el nombre del proyecto, están en Importar proyectos.

Recorrido por un monorepo

Este es el camino del código de principio a fin para un monorepo, sin descubrimiento con IA:

shop/
├── apps/
│   ├── storefront/
│   └── admin/
├── services/
│   ├── orders/
│   └── payments/
└── packages/
    └── ui/

1. Crea el proyecto y vincula el repositorio. Desde la raíz del monorepo:

archyl init --new --no-discover --name "Shop" --team platform

Esto escribe .archyl.json, que vincula el repositorio al proyecto. Haz commit de él: no contiene ningún secreto.

2. Modela un sistema con un contenedor por cada desplegable. Las aplicaciones y los servicios se convierten en contenedores. Un paquete compartido como packages/ui no suele ser un contenedor propio: descríbelo como un componente de los contenedores que lo usan, o déjalo fuera.

3. Da a cada contenedor el nombre de su carpeta. Esto es lo que permite a archyl brief, where, check, impact y al hook Guard saber a qué elemento pertenece un archivo modificado: un archivo pertenece a un elemento cuando una de las carpetas de su ruta tiene el nombre del elemento. La comparación ignora mayúsculas, espacios y puntuación, y una palabra final como API, Service o Worker, de modo que Orders Service coincide con services/orders/… y Payments API con services/payments/….

4. Elige un archivo o varios. Un único archyl.yaml en la raíz es lo más sencillo. Para un monorepo grande, da a cada servicio su propio archivo junto a su código e inclúyelos desde la raíz, de modo que cada equipo edite su parte:

# archyl.yaml
version: "1.0"
include:
  - apps/storefront/archyl.yaml
  - services/orders/archyl.yaml
  - services/payments/archyl.yaml
systems:
  - name: Shop
    description: The online shop
  - name: Stripe
    external: true

# 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

Las rutas de include son relativas al archivo que las declara, y las relaciones pueden apuntar a elementos de cualquiera de los archivos. Las reglas están en Include.

5. Haz push y comprueba.

archyl dsl diff
archyl dsl push
archyl where services/payments/internal/charge.go   # should name Payments API
archyl diagram "Payments API"                       # the container and its neighbours

Si where indica que un archivo no coincide, renombra el contenedor como su carpeta y vuelve a hacer push.

6. Mantenlo al día. Haz commit de archyl.yaml y de los archivos incluidos. Haz push desde CI cuando haya cambios, o usa Sincronizar ahora, que también obtiene del repositorio los archivos incluidos.

Y después, ponla a trabajar

Una vez que existe el modelo:

Conecta tus agentes de codificación con archyl setup (Claude Code, Cursor, VS Code, Codex), o desde el panel. Así llaman a plan, brief y al harness antes de cambiar código.
Comprueba los cambios contra él con archyl check y archyl review en CI. Consulta la guía de la CLI.
Incorpora a personas y agentes con archyl tour: un recorrido guiado por las partes que conviene conocer primero, con los archivos que leer. archyl tour --markdown > ONBOARDING.md lo deja por escrito.
Explóralo con archyl map, archyl diagram <element> o el lienzo de la aplicación.

Combinar caminos

Descubrir y después gestionar como código: ejecuta un descubrimiento, apruébalo, luego usa archyl dsl pull y haz commit de archyl.yaml a partir de entonces.
Escribir como código y después descubrir: un descubrimiento solo propone lo que el modelo aún no tiene, así que puede completar los componentes bajo los contenedores que escribiste. Revísalo como cualquier otro descubrimiento.
Dibujar en la aplicación y hacer push desde el código: ambos editan el mismo modelo. Un push actualiza lo que describe el archivo y deja el resto intacto.