Choisir comment démarrer

Un projet Archyl contient un modèle C4 de votre logiciel : systèmes, conteneurs, composants et code, ainsi que les relations entre eux. Il existe quatre façons de le remplir. Elles peuvent se combiner, et aucune ne vous enferme.

Quel que soit votre choix, la suite est la même : connecter vos agents de développement (voir « Puis le mettre au travail » plus bas) et garder le modèle synchronisé avec le code.

Le dessiner dans l'application

Créez un projet depuis le tableau de bord, puis ajoutez des systèmes, des conteneurs et des relations sur le canvas. Le guide de démarrage rapide vous accompagne étape par étape.

Dessiner est le bon point de départ pour un système qui n'existe pas encore, ou pour esquisser le contexte avant d'écrire du code. Vous pourrez passer au code plus tard : archyl dsl pull écrit ce que vous avez dessiné dans archyl.yaml.

Le découvrir avec l'IA

La découverte IA lit un dépôt connecté et propose des systèmes, conteneurs, composants, relations et technologies. Rien n'entre dans le modèle tant que vous ne l'avez pas approuvé.

Depuis l'application : connectez le dépôt dans Paramètres du projet › Intégration Git (voir Intégration Git), lancez une découverte, puis examinez ce qu'elle a trouvé.

Depuis le terminal, à la racine du dépôt :

archyl login
archyl init --new

init --new crée le projet, connecte le dépôt à partir de son remote git, lance la découverte sous vos yeux, ouvre la revue, dessine le résultat et propose de connecter vos agents de développement. Options utiles : --name, --team, --branch, --provider pour un remote auto-hébergé (github_enterprise, gitlab_private, gitea), et --yes pour accepter toutes les valeurs par défaut. Voir le guide de la CLI.

La découverte gère les monorepos : elle reconnaît apps/, packages/, services/ et libs/, et associe chaque service à un conteneur.

L'écrire en code

Décrivez l'architecture dans un fichier archyl.yaml à la racine du dépôt et poussez-le. Le format du fichier est décrit dans Architecture as Code.

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 fichier minimal :

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

Les éléments sont rapprochés par nom. Un push crée ce qui est nouveau et met à jour ce qui a changé, et ne supprime jamais rien : un élément que seul Archyl possède reste en place, et archyl dsl diff l'indique comme « only in Archyl ».

Votre agent de développement peut écrire la première version : lancez archyl setup, puis demandez-lui de décrire le dépôt dans archyl.yaml en suivant le schéma. C'est toujours à vous de relire le fichier.

Pour garder le fichier et le modèle synchronisés, committez archyl.yaml et poussez-le depuis la CI avec la GitHub Action, ou utilisez Synchroniser dans Paramètres du projet › Architecture as Code. archyl dsl diff --exit-code fait échouer un job de CI quand ils diffèrent.

L'importer depuis un autre outil

Depuis la liste des projets, cliquez sur Importer un projet et choisissez le format : Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON ou Backstage JSON. Un workspace Structurizr réparti en fichiers !include peut être envoyé sous forme de zip. Les détails, et l'endroit où chaque format conserve le nom du projet, se trouvent dans Importer des projets.

Parcours pour un monorepo

Voici le parcours par le code de bout en bout pour un monorepo, sans découverte IA :

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

1. Créez le projet et liez le dépôt. Depuis la racine du monorepo :

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

Cette commande écrit .archyl.json, qui relie le dépôt au projet. Committez-le : il ne contient aucun secret.

2. Modélisez un système avec un conteneur par unité déployable. Les applications et les services deviennent des conteneurs. Un package partagé comme packages/ui n'est généralement pas un conteneur à part entière : décrivez-le comme un composant des conteneurs qui l'utilisent, ou laissez-le de côté.

3. Nommez chaque conteneur d'après son dossier. C'est ce qui permet à archyl brief, where, check, impact et au hook Guard de savoir à quel élément appartient un fichier modifié : un fichier appartient à un élément quand l'un des dossiers de son chemin porte le nom de l'élément. La comparaison ignore la casse, les espaces et la ponctuation, ainsi qu'un mot final comme API, Service ou Worker : Orders Service correspond donc à services/orders/… et Payments API à services/payments/….

4. Choisissez un fichier ou plusieurs. Un seul archyl.yaml à la racine est le plus simple. Pour un grand monorepo, donnez à chaque service son propre fichier à côté de son code et incluez-les depuis la racine, pour que chaque équipe modifie sa partie :

# 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

Les chemins d'inclusion sont relatifs au fichier qui les déclare, et les relations peuvent pointer vers des éléments de n'importe lequel des fichiers. Les règles se trouvent dans Include.

5. Poussez et vérifiez.

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 signale un fichier sans correspondance, renommez le conteneur d'après son dossier et poussez à nouveau.

6. Gardez-le à jour. Committez archyl.yaml et les fichiers inclus. Poussez depuis la CI à chaque changement, ou utilisez Synchroniser, qui récupère aussi les fichiers inclus depuis le dépôt.

Puis le mettre au travail

Une fois le modèle en place :

• Connectez vos agents de développement avec archyl setup (Claude Code, Cursor, VS Code, Codex), ou depuis le tableau de bord. Ils appellent alors plan, brief et le harness avant de modifier le code.
• Vérifiez les changements avec archyl check et archyl review en CI. Voir le guide de la CLI.
• Intégrez les personnes et les agents avec archyl tour : une visite guidée des parties à connaître en premier, avec les fichiers à lire. archyl tour --markdown > ONBOARDING.md la met par écrit.
• Explorez-le avec archyl map, archyl diagram <element> ou le canvas de l'application.

Combiner les parcours

• Découvrir, puis gérer en code : lancez une découverte, approuvez-la, puis exécutez archyl dsl pull et committez archyl.yaml à partir de là.
• Écrire en code, puis découvrir : une découverte ne propose que ce que le modèle n'a pas déjà : elle peut donc compléter les composants sous les conteneurs que vous avez écrits. Examinez-la comme n'importe quelle autre découverte.
• Dessiner dans l'application et pousser depuis le code : les deux modifient le même modèle. Un push met à jour ce que décrit le fichier et laisse le reste intact.