Architecture as Code

Archyl vous permet de définir toute votre architecture C4 dans un seul fichier YAML : archyl.yaml. Versionnez-le dans votre dépôt, modifiez-le en même temps que votre code, et laissez votre CI/CD garder vos diagrammes synchronisés automatiquement.

Présentation

Le fichier archyl.yaml est une description déclarative de votre architecture. Il prend en charge :

• Les quatre niveaux C4 (systèmes, conteneurs, composants, code)
• Les relations entre n'importe quels éléments
• Les technologies, les environnements et les releases
• Les ADR, la documentation, les contrats d'API et les canaux d'événements
• Les overlays visuels pour regrouper des éléments sur les diagrammes
• Les monorepos via include

Vous pouvez l'écrire à la main, l'exporter depuis un projet existant, ou combiner les deux approches.

Format du fichier

Archyl cherche le fichier DSL à la racine du dépôt, en essayant ces noms dans l'ordre :

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

Référence du schéma

Structure racine

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: [...]

Seul version est obligatoire. Toutes les autres sections sont facultatives : n'incluez que ce dont vous avez besoin.

Systèmes (niveau C4 1)

Les systèmes sont les éléments de plus haut niveau du modèle 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: [...]

Conteneurs (niveau C4 2)

Les conteneurs sont imbriqués dans leur système parent.

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: [...]

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

Lorsque vous utilisez include pour les fichiers d'un monorepo, indiquez avec parent_system le système auquel appartient ce conteneur :

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

Composants (niveau C4 3)

Les composants sont imbriqués dans leur conteneur parent.

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: [...]

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

Éléments de code (niveau C4 4)

Les éléments de code sont imbriqués dans leur composant parent.

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

Types d'éléments de code disponibles : class, interface, struct, function, method, enum, constant, type.

Relations

Les relations relient deux éléments quelconques, avec la notation pointée pour les références imbriquées.

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

Format de la notation pointée : System.Container.Component.CodeElement. N'utilisez que le nombre de niveaux nécessaire : Payment Service référence le système, Payment Service.API Gateway référence un conteneur.

Types de relations disponibles : uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from.

Technologies

Définissez un catalogue des technologies utilisées dans votre architecture.

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

Catégories disponibles : programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.

Environnements

Définissez les environnements de déploiement de vos releases.

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

Releases

Suivez les déploiements versionnés à travers les environnements et les éléments.

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"

Canaux d'événements

Définissez la messagerie asynchrone entre services.

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

Contrats d'API

Rattachez des spécifications d'API à votre architecture.

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

Vous pouvez utiliser file pour référencer un fichier de spécification dans le dépôt, ou content pour intégrer directement la spécification.

Architecture Decision Records (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

Documentation

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

Vous pouvez utiliser file pour référencer un fichier markdown dans le dépôt, ou content pour intégrer directement le contenu.

Overlays

Des regroupements visuels qui apparaissent sur le diagramme.

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 (prise en charge des monorepos)

Pour les monorepos, répartissez votre architecture sur plusieurs fichiers et fusionnez-les :

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

Chaque fichier inclus suit le même schéma. Utilisez parent_system sur les conteneurs pour indiquer à quel système ils appartiennent lorsqu'ils sont définis dans un fichier séparé.

Exemple complet

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"

Synchroniser depuis un dépôt

Si votre dépôt contient un archyl.yaml, vous pouvez le synchroniser directement depuis l'interface d'Archyl :

1. Allez dans Paramètres du projet > Architecture as Code
2. Cliquez sur Synchroniser

Archyl récupère le fichier sur la branche par défaut de votre dépôt (ou sur la branche configurée dans les paramètres DSL) et l'importe. Les éléments qui existent déjà sont mis à jour ; les nouveaux éléments sont créés.

Intégration CI/CD

GitHub Action (officielle)

La GitHub Action officielle archyl-com/actions/sync est le moyen le plus simple de garder votre architecture synchronisée. Elle lit votre archyl.yaml, l'envoie à l'API Archyl et indique ce qui a été créé ou mis à jour.

Configuration minimale :

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'

Avec le résumé en sortie :

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

Chemin de fichier personnalisé (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 auto-hébergé :

- 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'

Entrées de l'action

Sorties de l'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

Vous pouvez envoyer du contenu DSL depuis n'importe quel système CI/CD ou 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 .)}"

L'endpoint d'ingestion renvoie un résumé de ce qui a été créé :

{
  "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
  }
}

Exporter en YAML

Vous pouvez exporter n'importe quel projet existant sous forme de fichier archyl.yaml :

1. Ouvrez votre projet
2. Cliquez sur Exporter dans la barre d'outils
3. Sélectionnez YAML (Architecture as Code)

Cela génère un archyl.yaml complet que vous pouvez versionner dans votre dépôt. C'est un excellent moyen d'amorcer le fichier à partir d'un projet existant ou d'une architecture découverte par l'IA.

Vous pouvez aussi exporter via l'API :

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

JSON Schema pour les IDE

Archyl fournit un JSON Schema pour les fichiers archyl.yaml, afin que votre éditeur propose l'autocomplétion et la validation. Le schéma est disponible à l'adresse :

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

VS Code

Ajoutez ceci à votre archyl.yaml pour activer la validation par le schéma :

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

Ou configurez-le globalement dans les paramètres de VS Code :

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

Export en image et PDF

Archyl permet aussi d'exporter vos diagrammes sous forme d'images pour les présentations et les documents.

Formats disponibles

Comment exporter

1. Naviguez vers le niveau C4 que vous voulez exporter
2. Cliquez sur Exporter dans la barre d'outils
3. Sélectionnez votre format (PNG, SVG ou PDF)
4. Configurez les options (arrière-plan, qualité, cadrage)
5. Cliquez sur Exporter

Cochez Exporter tous les niveaux pour générer un fichier distinct pour chaque niveau C4.

Options d'export

• Arrière-plan : inclure l'arrière-plan sombre du canevas ou exporter sur fond transparent
• Qualité (PNG uniquement) : résolution Standard, Haute ou Impression
• Cadrage : ajuster au contenu, ajouter une marge ou exporter la vue actuelle

Importer des projets

Vous pouvez créer un nouveau projet en important depuis plusieurs formats. Archyl prend en charge cinq sources d'import :

Comment importer

1. Depuis votre liste de projets, cliquez sur Importer un projet
2. Sélectionnez l'onglet du format source (Archyl YAML, Structurizr DSL, LikeC4, IcePanel ou Backstage)
3. Téléversez le fichier ou collez son contenu
4. Cliquez sur Valider pour prévisualiser ce qui sera créé
5. Cliquez sur Créer le projet

L'ensemble du processus prend moins d'une minute. Tous les systèmes, conteneurs, composants, relations, technologies et tags sont importés automatiquement.

Nom et description du projet

La création d'un projet exige un nom, et chaque format le porte à un endroit différent. Un nom absent est la cause la plus fréquente d'un import refusé.

Seuls Archyl YAML et Structurizr DSL peuvent échouer sur ce contrôle. Les autres formats retombent toujours sur un nom généré que vous pouvez modifier après l'import.

Pour Structurizr, le nom et la description sont les deux chaînes optionnelles de l'en-tête 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 { ... } sans nom s'analyse correctement mais ne peut pas créer de projet : Archyl le refuse et vous demande de nommer le workspace. L'import dans un projet existant n'a pas cette contrainte : le nom du workspace y est ignoré, puisque le projet en a déjà un.

Import Structurizr DSL

Archyl analyse les fichiers workspace .dsl de Structurizr et extrait le modèle C4 complet :

• Les éléments person, softwareSystem, container et component
• Toutes les relations ->, avec leurs descriptions et technologies
• La détection des systèmes externes à partir des tags
• L'extraction des technologies depuis les arguments positionnels
• Les groupes, convertis en tags

Les vues, styles, thèmes et nœuds de déploiement sont ignorés (Archyl a sa propre couche visuelle).

Le nom et la description du workspace deviennent le nom et la description du projet : voir la section Nom et description du projet ci-dessus. Un workspace sans nom peut être importé dans un projet existant, mais ne peut pas en créer un.

Workspaces multi-fichiers (!include)

Un workspace réparti sur plusieurs fichiers — !include systems/payments.dsl et consorts — ne peut pas être importé en un seul fichier, puisque les fichiers inclus ne sont pas là pour être résolus. Téléversez plutôt tout le workspace sous forme de .zip, dans l'onglet Structurizr DSL : les fichiers de l'archive sont extraits et chaque !include est résolu à partir d'eux.

• Le point d'entrée est workspace.dsl si l'archive en contient un, sinon le fichier .dsl le moins profond. Archyl indique quel fichier a été utilisé.
• Les chemins sont résolus relativement au fichier qui inclut, donc les includes imbriqués fonctionnent.
• Inclure un répertoire intègre tous les .dsl qui s'y trouvent directement, par ordre de nom.
• Les cycles d'inclusion sont rompus et signalés, sans faire échouer l'import.
• Les cibles distantes (!include https://…) sont refusées, et les chemins sortant de l'archive sont ignorés.

Tout ce qui ne peut pas être résolu devient un avertissement sur le résultat de l'import : le reste du workspace est quand même importé.

Limites de l'archive :

Seuls les fichiers .dsl, .md, .json, .yaml, .yml et .txt sont conservés ; tout le reste de l'archive est ignoré.

Via l'API, envoyez l'archive en données de formulaire multipart dans un champ file, avec un champ entry facultatif qui désigne le point d'entrée : POST /api/v1/dsl/validate-archive la vérifie, POST /api/v1/projects/{id}/dsl/import-archive l'importe dans un projet, et POST /api/v1/dsl/import-project-archive crée un projet à partir d'elle. L'outil MCP import_dsl et la synchronisation de dépôt lisent un seul fichier et ne résolvent pas les !include.

Import LikeC4

Archyl est le premier outil à importer des fichiers LikeC4. L'importeur gère les spécificités de LikeC4 :

• Types d'éléments personnalisés des blocs specification, associés aux niveaux C4
• Hiérarchies d'éléments imbriqués résolues en systèmes, conteneurs et composants
• Propriétés technology: et description: (avec ou sans la syntaxe à deux-points)
• Tags #hashtag convertis en tags standard
• Détection du tag #external pour distinguer les éléments internes et externes
• Blocs model multiples fusionnés automatiquement
• Chaînes entre guillemets simples et entre triples guillemets prises en charge

Import IcePanel JSON

Le format d'export JSON d'IcePanel est entièrement pris en charge :

• Types d'objets system, actor, app, store et component associés aux éléments C4
• Champ external: true pour classer les systèmes externes
• modelConnections converties en relations
• tagIds résolus en noms de tags à partir du tableau tags
• Objets domain utilisés comme nom de projet

Import Backstage

Archyl importe le JSON du Software Catalog renvoyé par l'endpoint /api/catalog/entities de Backstage :

• Entités System converties en systèmes Archyl (les collisions entre namespaces sont levées automatiquement)
• Entités Component et Resource rattachées en tant que conteneurs sous leur système d'appartenance (via spec.system ou la relation partOf)
• Components et Resources sans système parent regroupés sous un système synthétique Uncategorized
• Types de Resource associés aux types de conteneurs Archyl : s3-bucket → file_storage ; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database ; kafka-topic, sqs-queue → message_queue ; repository → library ; tout le reste → infrastructure
• Types de Component associés : service → service, cronworkflow → worker, website → web_app, library → library
• Entités API importées comme Contrats d'API, avec le spec.definition inline (OpenAPI / gRPC / GraphQL / AsyncAPI) conservé comme contenu et lié aux composants qui le fournissent ou le consomment
• dependsOn, consumesApi, producesTo, consumesFrom, versionedIn (et leurs inverses) traduits en relations Archyl
• metadata.namespace, spec.lifecycle et spec.type exposés comme tags
• Entités User et Group ignorées : le graphe des personnes et des équipes de Backstage n'est pas un concept C4

Pour exporter votre catalogue :

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

Déposez ensuite entities.json dans l'onglet Backstage de la fenêtre d'import. Les listes de ressources des gros catalogues peuvent produire des milliers de conteneurs : vérifiez le résultat et supprimez ce dont vous n'avez pas besoin.

Import via MCP (agents IA)

La même capacité d'import est disponible via l'outil 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"

Cela permet aux agents de code IA (Claude Code, Cursor, Windsurf) d'importer des fichiers d'architecture par programmation.

Import dans des projets existants

Vous pouvez aussi importer dans un projet existant (et pas seulement en créer de nouveaux) :

1. Ouvrez votre projet
2. Allez dans Architecture as Code
3. Cliquez sur Importer
4. Sélectionnez le format et téléversez le fichier

Les éléments qui existent déjà sont mis à jour ; les nouveaux éléments sont créés.

Étapes suivantes

• Vue d'ensemble de l'API — Référence complète de l'API pour les endpoints DSL
• Partage et intégration — Partagez des diagrammes en direct
• Gestion des releases — Suivez les déploiements dans votre YAML
• Notifications webhook — Soyez notifié quand l'architecture change