Il modello C4 in YAML: il formato archyl.yaml e il workflow Git

I diagrammi di architettura hanno un problema di scadenza. Li disegni dopo una sessione di design, sono perfetti per una settimana, e poi il codice evolve mentre i diagrammi marciscono. Sei mesi dopo, il nuovo assunto fissa un diagramma dei Container che mostra tre servizi fusi nel Q2 e non menziona i due costruiti nel Q3.

In Archyl siamo ossessionati da questo problema dal primo giorno. La scoperta tramite IA aiuta a tenere le cose aggiornate. L'editor visuale rende gli aggiornamenti indolori. Ma c'è una categoria di team (quelli che trattano l'infrastruttura come codice, le policy come codice, tutto come codice) che voleva qualcosa di più fondamentale.

Volevano che la loro architettura vivesse in Git, accanto al codice che descrive. Oggi rilasciamo esattamente questo.

Questo post è il riferimento per il file in sé: cosa contiene, come si risolvono i riferimenti e come si sincronizza. Per le ragioni più generali dell'architecture as code, e per il confronto con formati come Structurizr DSL, leggi la guida all'architecture as code.

Cos'è archyl.yaml?

È un unico file YAML che descrive in modo dichiarativo la tua architettura completa. Mettilo nella root del repository e diventa la fonte di verità del tuo modello C4 in Archyl.

Ecco come appare un file minimo:

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

Tutto qui. Archyl legge questo file, costruisce il modello C4 completo, genera i diagrammi e mantiene tutto sincronizzato. Niente clic nelle interfacce, niente sincronizzazioni manuali, niente "mi sono dimenticato di aggiornare il diagramma".

Chiavi di primo livello

Al primo livello è obbligatorio solo version. Tutto il resto è facoltativo, quindi un file può partire da un solo sistema e crescere.

Tutto in un unico file

Il DSL non è un sottoinsieme semplificato: copre tutto ciò che Archyl può modellare.

Tutti e quattro i livelli C4. I sistemi contengono container, i container contengono componenti, i componenti contengono elementi di codice. L'annidamento YAML rispecchia direttamente la gerarchia.

Relazioni con notazione a punti. Collega due elementi qualsiasi con riferimenti leggibili come Payment Service.API Gateway → Payment Service.Database. Niente UUID, niente identificatori criptici. Cercabili con grep, adatti ai diff, leggibili da persone.

Tecnologie, ambienti e rilasci. Definisci il tuo catalogo di tecnologie, dichiara gli ambienti di deployment (staging, produzione) e traccia i rilasci, tutto dallo stesso file.

ADR e documentazione. Scrivi gli Architecture Decision Record inline o punta a una cartella nel tuo repo. Lo stesso vale per la documentazione di progetto.

Contratti API e canali di eventi. Dichiara le tue specifiche OpenAPI, le definizioni gRPC, i topic Kafka, e collegali ai componenti che li espongono o li consumano.

Overlay visivi. Raggruppa gli elementi sul diagramma con overlay dotati di nome, controllando colori e livelli.

Supporto ai monorepo. Usa include per suddividere la tua architettura in più file (uno per servizio, team o bounded context) e Archyl li unisce automaticamente.

Perché YAML?

Abbiamo valutato una sintassi DSL personalizzata (come il DSL di Structurizr o l'HCL di Terraform). Abbiamo scelto YAML per ragioni pratiche:

1. Curva di apprendimento nulla. Ogni sviluppatore conosce già YAML. Nessuna nuova sintassi da imparare, nessun parser da installare, nessun plugin per l'editor.

2. Supporto IDE gratuito. Pubblichiamo un JSON Schema su /api/v1/dsl/schema. Punta il tuo IDE lì e ottieni autocompletamento, validazione e documentazione inline senza strumenti specifici di Archyl.

3. Adatto ai diff. I diff YAML sono puliti e leggibili nelle pull request. I revisori vedono subito "ah, hanno aggiunto un nuovo container al Payment Service e l'hanno collegato a Redis".

4. Ecosistema di strumenti. Linter, formatter, motori di template (Helm, Kustomize): funzionano tutti con YAML senza configurazione.

Il workflow nativo Git

Ecco dove sta la vera forza. Poiché archyl.yaml vive nel tuo repository, le modifiche all'architettura seguono lo stesso workflow delle modifiche al codice:

1. Branch. Crea un feature branch, modifica lo YAML.
2. Review. Apri una pull request. Il team revisiona la modifica all'architettura insieme a quella al codice.
3. Merge. Una volta approvata, fai il merge su main.
4. Sync. Archyl recepisce la modifica e aggiorna i diagrammi automaticamente.

Basta "il diagramma dice X ma il codice fa Y". Basta modifiche all'architettura che aggirano la review. Basta documentazione di cui nessuno sa che è stata aggiornata.

Integrazione CI/CD

Abbiamo costruito un'integrazione di prima classe con le pipeline CI/CD. Per GitHub distribuiamo una GitHub Action ufficiale che gestisce tutto: legge il file, chiama l'API e riporta cosa è cambiato.

GitHub Actions (action ufficiale):

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'

Tutto qui. Tre righe di configurazione e la tua architettura resta sincronizzata a ogni push. L'action supporta percorsi di file personalizzati (per i monorepo), istanze Archyl self-hosted, ed espone output come summary, systems-created e relationships-created per i passi successivi.

GitLab CI:

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

L'endpoint /ingest accetta l'autenticazione tramite API key, quindi in CI non serve alcun flusso OAuth. Importa il modello completo, crea o aggiorna ogni elemento e restituisce un riepilogo dettagliato di cosa è cambiato.

Puoi anche sincronizzare direttamente dall'interfaccia di Archyl. Se il tuo progetto ha un repository Git collegato, premi "Sincronizza ora" nelle impostazioni di Architecture as Code e Archyl recupera il file direttamente dal tuo repo.

Bidirezionale: export e import

Il workflow non va in una sola direzione. Hai già un progetto modellato nell'editor visuale di Archyl? Esportalo:

• Export genera un archyl.yaml completo dal modello attuale. Ogni sistema, container, componente, relazione, overlay, ADR, contratto API, canale di eventi, rilascio: tutto serializzato in YAML pulito.
• Import analizza un archyl.yaml e crea o aggiorna tutti gli elementi del progetto. È idempotente: importare due volte lo stesso file non crea duplicati. Gli elementi vengono abbinati per nome e aggiornati o creati.
• Import as Project crea un progetto completamente nuovo da un file YAML. Carica un archyl.yaml e ottieni un progetto già popolato con un solo clic.

Puoi quindi partire dall'interfaccia, esportare in YAML, fare commit su Git e passare al workflow code-first, o fare il percorso inverso. Nessun lock-in su nessuno dei due approcci.

Risoluzione intelligente dei riferimenti

Una delle parti più delicate del DSL è risolvere i riferimenti agli elementi in relazioni, overlay, eventi e contratti API. Abbiamo costruito un resolver che lo fa in modo naturale:

• I nomi brevi funzionano quando non sono ambigui: API Gateway si risolve direttamente se un solo elemento ha quel nome.
• La notazione a punti scioglie le ambiguità: Payment Service.API Gateway vs Analytics.API Gateway.
• Funziona a qualsiasi profondità: System.Container.Component.CodeElement per i riferimenti annidati in profondità.

Il resolver indicizza ogni elemento a ogni profondità di percorso possibile, così usi sempre il riferimento più breve non ambiguo. Gli export usano la stessa logica al contrario, producendo i riferimenti più leggibili possibile.

Validazione senza effetti collaterali

Non sei sicuro che il tuo YAML sia valido? L'endpoint /validate (e il pulsante "Valida" nella finestra di importazione) analizza e verifica il file senza toccare il database:

• Controllo della versione dello schema
• Validazione dei campi obbligatori
• Rilevamento dei nomi duplicati
• Validazione dei valori enumerati (tipi di container, tipi di relazione, ecc.)
• Risoluzione dei riferimenti incrociati

Gli errori tornano con percorsi precisi (systems[2].containers[1].name) e messaggi chiari. Collegalo a un hook di pre-commit o a un controllo in CI e intercetta i problemi prima che arrivino su main.

Pattern reali

Il monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

Ogni servizio mantiene il proprio archyl.yaml con i suoi container e componenti. Il file root li unisce, e le relazioni tra servizi sono definite a livello root. Tecnologie e ambienti vengono deduplicati automaticamente.

Il bootstrap

Stai avviando un nuovo progetto? Crea un archyl.yaml prima di scrivere codice. Definisci i sistemi e i container che intendi costruire. Usa "Import as Project" di Archyl per generare subito l'architettura. Man mano che costruisci, lo YAML evolve insieme al codice.

La traccia di audit

Poiché lo YAML è in Git, hai gratis tutta la cronologia. git log archyl.yaml mostra ogni modifica all'architettura, chi l'ha fatta, quando, e la PR in cui è stata discussa. Prova a ottenerlo da uno strumento di diagrammi.

Il generatore di documentazione

Esporta la tua architettura in YAML, poi passala in qualsiasi motore di template per generare documentazione Markdown, pagine Confluence o wiki interni. Il formato strutturato rende l'automazione banale.

Cosa arriva dopo

Questa è la versione 1.0 del formato DSL. Ecco su cosa stiamo lavorando:

Rilevamento del drift. Confrontare lo YAML nel tuo repo con il modello live ed evidenziare le differenze: elementi aggiunti nell'interfaccia ma non nel file, o viceversa.

Commenti di anteprima sulle PR. Quando una PR modifica archyl.yaml, un bot commenta con un diff visivo di cosa è cambiato nell'architettura.

Evoluzione dello schema. Man mano che aggiungiamo funzionalità ad Archyl, il DSL crescerà. Manterremo la retrocompatibilità e forniremo strumenti di migrazione.

Provalo ora

Architecture as Code è disponibile oggi su tutti i piani di Archyl. Se hai già un progetto:

1. Vai alla pagina Architecture as Code del tuo progetto
2. Clicca su Export per generare il tuo archyl.yaml
3. Fai commit nel tuo repository
4. Aggiungi la GitHub Action ufficiale al tuo workflow e hai finito

Se parti da zero, crea un archyl.yaml, usa Import as Project e avrai un'architettura C4 completamente renderizzata in pochi secondi.

La tua architettura merita lo stesso rigore del tuo codice. Versionala, revisionala, automatizzala.

Nuovo al C4? Inizia dalla nostra guida al modello C4. Vuoi che l'IA generi l'architettura iniziale? Vedi Scoperta dell'architettura con l'IA. Usi già assistenti IA? Collegali tramite il nostro server MCP.