Abbiamo appena rilasciato la funzionalità che trasforma la documentazione dell'architettura in un cittadino di prima classe della tua codebase. Ecco archyl.yaml — un DSL dichiarativo che descrive il tuo modello C4 completo, vive in Git, passa attraverso la code review e si sincronizza automaticamente via CI/CD.

Architecture as Code: Definisci il tuo intero modello C4 in un file YAML

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 arrivato fissa un diagramma Container che mostra tre servizi unificati nel Q2 e non menziona i due costruiti nel Q3.

Siamo ossessionati da questo problema fin dal primo giorno di Archyl. La scoperta tramite IA aiuta a mantenere 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 volevano qualcosa di più fondamentale.

Volevano che la loro architettura vivesse in Git, accanto al codice che descrive. Oggi, è esattamente quello che stiamo rilasciando.

Cos'è `archyl.yaml`?

È un singolo file YAML che descrive in modo dichiarativo la tua architettura completa. Posizionalo alla radice del tuo repository e diventa la fonte di verità per il 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, renderizza i diagrammi e mantiene tutto sincronizzato. Niente clic nelle interfacce, niente sincronizzazione manuale, niente "ho dimenticato di aggiornare il diagramma".

Tutto in un unico file

Il DSL non è un sottoinsieme semplificato — copre l'intero ambito di 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 qualsiasi coppia di elementi usando riferimenti leggibili come Payment Service.API Gateway → Payment Service.Database. Niente UUID, niente identificatori criptici. Compatibile con grep, compatibile con i diff, leggibile dagli umani.

Tecnologie, ambienti e release. Definisci il tuo catalogo tecnologico, dichiara gli ambienti di deployment (staging, produzione) e traccia le release — tutto dallo stesso file.

ADR e documentazione. Integra i tuoi Architecture Decision Record inline o punta a una cartella nel tuo repository. Lo stesso per la documentazione del progetto.

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

Overlay visuali. Raggruppa elementi nel diagramma con overlay nominati, controllando colori e livelli.

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

Perché YAML?

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

Zero curva di apprendimento. Ogni sviluppatore conosce già YAML. Nessuna nuova sintassi da imparare, nessun parser da installare, nessun plugin per l'editor richiesto.
Supporto IDE gratuito. Pubblichiamo un JSON Schema su /api/v1/dsl/schema. Punta il tuo IDE e ottieni autocompletamento, validazione e documentazione inline senza strumenti specifici per Archyl.
Compatibile con i diff. I diff YAML sono puliti e leggibili nelle pull request. I revisori vedono immediatamente "ah, hanno aggiunto un nuovo container al Payment Service e lo hanno collegato a Redis".
Ecosistema di strumenti. Linter, formatter, motori di template (Helm, Kustomize), tutto funziona con YAML nativamente.

Il workflow Git-nativo

Qui risiede il vero potere. Poiché archyl.yaml vive nel tuo repository, i cambiamenti di architettura seguono lo stesso workflow dei cambiamenti di codice:

Branch. Crea un branch feature, modifica il YAML.
Review. Apri una pull request. Il tuo team rivede il cambiamento di architettura insieme al cambiamento di codice.
Merge. Una volta approvato, merge in main.
Sync. Archyl rileva il cambiamento e aggiorna i diagrammi automaticamente.

Basta con "il diagramma dice X ma il codice fa Y". Basta con cambiamenti di architettura che aggirano la review. Basta con documentazione che nessuno sa essere stata aggiornata.

Integrazione CI/CD

Abbiamo costruito un'integrazione di prima classe con le pipeline CI/CD. Per GitHub, forniamo una GitHub Action ufficiale che gestisce tutto — lettura del file, chiamata all'API e report di 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 ad ogni push. L'action supporta percorsi file personalizzati (per monorepo), istanze Archyl self-hosted, ed espone output come summary, systems-created e relationships-created per gli step 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 autenticazione via API key, quindi non è necessario nessun flusso OAuth in CI. 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 connesso, clicca su "Sincronizza ora" nelle impostazioni Architecture as Code e Archyl recupera il file direttamente dal tuo repository.

Bidirezionale: Export e Import

Il workflow non è unidirezionale. Hai già un progetto modellato nell'editor visuale di Archyl? Esportalo:

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

Questo significa che puoi iniziare nell'interfaccia, esportare in YAML, committare in Git e passare al workflow code-first — o viceversa. Nessun lock-in su nessuno dei due approcci.

Risoluzione intelligente dei riferimenti

Una delle parti più complicate del DSL è la risoluzione dei riferimenti degli elementi nelle relazioni, overlay, eventi e contratti API. Abbiamo costruito un resolver che gestisce tutto in modo naturale:

Nomi brevi quando non c'è ambiguità: API Gateway si risolve direttamente se solo un elemento ha quel nome.
Notazione a punti per disambiguare: Payment Service.API Gateway vs Analytics.API Gateway.
Qualsiasi profondità funziona: System.Container.Component.CodeElement per riferimenti profondamente annidati.

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

Validazione senza effetti collaterali

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

Verifica della versione dello schema
Validazione dei campi obbligatori
Rilevamento di nomi duplicati
Validazione dei tipi enumerati (tipi di container, tipi di relazioni, ecc.)
Risoluzione dei riferimenti incrociati

Gli errori tornano con percorsi precisi (systems[2].containers[1].name) e messaggi chiari. Integralo in un hook pre-commit o in un check CI e intercetta i problemi prima che raggiungano main.

Pattern del mondo reale

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 che definisce i suoi container e componenti. Il file root li unisce, e le relazioni tra servizi vengono definite a livello root. Le tecnologie e gli ambienti vengono deduplicati automaticamente.

Il Bootstrapper

Stai iniziando un nuovo progetto? Crea un archyl.yaml prima di scrivere codice. Definisci i sistemi e i container che prevedi di costruire. Usa "Import as Project" di Archyl per generare l'architettura istantaneamente. Man mano che costruisci, il YAML evolve con il codice.

La traccia di audit

Poiché il YAML è in Git, ottieni la cronologia completa gratuitamente. git log archyl.yaml mostra ogni cambiamento di architettura, chi l'ha fatto, quando, e la PR dove è stato discusso. Prova a ottenere lo stesso da uno strumento di diagrammi.

Il generatore di documentazione

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

Cosa c'è dopo

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

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

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

Evoluzione dello schema. Man mano che aggiungiamo nuove funzionalità ad Archyl, il DSL crescerà. Manterremo la compatibilità all'indietro e forniremo strumenti di migrazione.

Provalo ora

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

Vai alla pagina Architecture as Code nel tuo progetto
Clicca su Export per generare il tuo archyl.yaml
Committalo nel tuo repository
Aggiungi la GitHub Action ufficiale al tuo workflow e il gioco è fatto

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 con la nostra Introduzione al modello C4. Vuoi che l'IA generi l'architettura iniziale? Vedi Scoperta dell'architettura con IA. Usi già assistenti IA? Collegali tramite il nostro Server MCP.

Architecture as Code: Definisci il tuo intero modello C4 in un file YAML - Archyl Blog