Architettura come Codice

Archyl ti permette di definire l'intera architettura C4 in un unico file YAML: archyl.yaml. Aggiungilo al tuo repository, modificalo insieme al codice e lascia che la CI/CD mantenga automaticamente sincronizzati i diagrammi.

Panoramica

Il file archyl.yaml è una descrizione dichiarativa della tua architettura. Supporta:

• Tutti e quattro i livelli C4 (sistemi, container, componenti, codice)
• Relazioni tra qualsiasi elemento
• Tecnologie, ambienti e release
• ADR, documentazione, contratti API e canali di eventi
• Overlay visivi per raggruppare gli elementi nei diagrammi
• Supporto monorepo tramite include

Puoi scriverlo a mano, esportarlo da un progetto esistente o combinare i due approcci.

Formato del file

Archyl cerca il file DSL nella radice del repository, provando questi nomi nell'ordine:

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

Riferimento dello schema

Struttura radice

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

Solo version è obbligatorio. Tutte le altre sezioni sono facoltative: includi solo ciò che ti serve.

Sistemi (livello C4 1)

I sistemi sono gli elementi di primo livello del modello 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: [...]

Container (livello C4 2)

I container sono annidati nel sistema a cui appartengono.

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

Tipi di container disponibili: web_app, mobile_app, desktop_app, api, database, file_storage, message_queue, cache, service, function, worker, consumer, infrastructure, gateway, library.

Quando usi include per i file di un monorepo, usa parent_system per indicare a quale sistema appartiene il container:

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

Componenti (livello C4 3)

I componenti sono annidati nel container a cui appartengono.

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

Tipi di componente disponibili: controller, service, repository, handler, middleware, model, util, config, adapter, port, resource, module, job, bundle, plugin, workflow, activity, entity.

Elementi di codice (livello C4 4)

Gli elementi di codice sono annidati nel componente a cui appartengono.

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

Tipi di elemento di codice disponibili: class, interface, struct, function, method, enum, constant, type.

Relazioni

Le relazioni collegano due elementi qualsiasi usando la notazione a punti per i riferimenti annidati.

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

Formato della notazione a punti: System.Container.Component.CodeElement. Usa solo i livelli necessari: Payment Service fa riferimento al sistema, Payment Service.API Gateway a un container.

Tipi di relazione disponibili: uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from.

Tecnologie

Definisci un catalogo delle tecnologie usate nella tua architettura.

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

Categorie disponibili: programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.

Ambienti

Definisci gli ambienti di deployment per le tue release.

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

Release

Traccia i deployment versionati tra ambienti ed elementi.

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"

Canali di eventi

Definisci la messaggistica asincrona tra i servizi.

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

Contratti API

Collega le specifiche API alla tua architettura.

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

Puoi usare file per fare riferimento a un file di specifica nel repository, oppure content per inserire la specifica direttamente.

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

Documentazione

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

Puoi usare file per fare riferimento a un file markdown nel repository, oppure content per inserire il contenuto direttamente.

Overlay

Raggruppamenti visivi che compaiono sul diagramma.

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 (supporto monorepo)

Nei monorepo, suddividi l'architettura su più file e uniscili:

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

Ogni file incluso segue lo stesso schema. Usa parent_system sui container per indicare a quale sistema appartengono quando sono definiti in un file separato.

Esempio completo

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"

Sincronizzazione da un repository

Se il tuo repository contiene un archyl.yaml, puoi sincronizzarlo direttamente dall'interfaccia di Archyl:

1. Vai su Impostazioni Progetto > Architettura come Codice
2. Clicca su Sincronizza ora

Archyl recupera il file dal branch predefinito del repository (o dal branch configurato nelle impostazioni DSL) e lo importa. Gli elementi già esistenti vengono aggiornati; i nuovi elementi vengono creati.

Integrazione CI/CD

GitHub Action (ufficiale)

La GitHub Action ufficiale archyl-com/actions/sync è il modo più semplice per mantenere sincronizzata la tua architettura. Legge il tuo archyl.yaml, lo invia all'API di Archyl e riporta cosa è stato creato o aggiornato.

Configurazione minima:

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'

Con output di riepilogo:

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

Percorso del file personalizzato (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 self-hosted:

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

Input dell'action

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

Puoi inviare contenuto DSL da qualsiasi sistema CI/CD o 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 di ingestione restituisce un riepilogo di ciò che è stato creato:

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

Esportazione in YAML

Puoi esportare qualsiasi progetto esistente come file archyl.yaml:

1. Apri il tuo progetto
2. Clicca su Esporta nella barra degli strumenti
3. Seleziona YAML (Architettura come Codice)

Viene generato un archyl.yaml completo che puoi aggiungere al tuo repository. È un ottimo modo per creare il file a partire da un progetto esistente o da un'architettura scoperta con l'IA.

Puoi anche esportare tramite 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 per il supporto negli IDE

Archyl fornisce un JSON Schema per i file archyl.yaml, così il tuo editor può offrire autocompletamento e validazione. Lo schema è disponibile all'indirizzo:

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

VS Code

Aggiungi questa riga al tuo archyl.yaml per abilitare la validazione dello schema:

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

Oppure configuralo globalmente nelle impostazioni di VS Code:

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

Esportazione di immagini e PDF

Archyl supporta anche l'esportazione dei diagrammi come immagini per presentazioni e documenti.

Formati disponibili

Come esportare

1. Vai al livello C4 che vuoi esportare
2. Clicca su Esporta nella barra degli strumenti
3. Seleziona il formato (PNG, SVG o PDF)
4. Configura le opzioni (sfondo, qualità, viewport)
5. Clicca su Esporta

Seleziona Esporta tutti i livelli per generare un file separato per ogni livello C4.

Opzioni di esportazione

• Sfondo: includi lo sfondo scuro del canvas oppure usa uno sfondo trasparente
• Qualità (solo PNG): risoluzione Standard, Alta o Stampa
• Viewport: adatta al contenuto, includi un margine oppure esporta la vista corrente

Importazione di progetti

Puoi creare un nuovo progetto importandolo da diversi formati. Archyl supporta cinque fonti di importazione:

Come importare

1. Dall'elenco dei progetti, clicca su Importa progetto
2. Seleziona la scheda del formato di origine (Archyl YAML, Structurizr DSL, LikeC4, IcePanel o Backstage)
3. Carica il file o incollane il contenuto
4. Clicca su Valida per visualizzare l'anteprima di ciò che verrà creato
5. Clicca su Crea progetto

L'intero processo richiede meno di un minuto. Tutti i sistemi, container, componenti, relazioni, tecnologie e tag vengono importati automaticamente.

Nome e descrizione del progetto

La creazione di un progetto richiede un nome, e ogni formato lo riporta in un punto diverso. Un nome mancante è la causa più frequente di un'importazione rifiutata.

Solo Archyl YAML e Structurizr DSL possono non superare questo controllo. Gli altri formati ricorrono sempre a un nome generato, che puoi cambiare dopo l'importazione.

In Structurizr, nome e descrizione sono le due stringhe facoltative dell'intestazione 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 { ... } senza nome viene analizzato correttamente ma non può creare un progetto: Archyl lo rifiuta e ti chiede di dare un nome al workspace. L'importazione in un progetto esistente non ha questo vincolo: lì il nome del workspace viene ignorato, perché il progetto ne ha già uno.

Importazione Structurizr DSL

Archyl analizza i file workspace .dsl di Structurizr ed estrae il modello C4 completo:

• Elementi person, softwareSystem, container, component
• Tutte le relazioni -> con descrizioni e tecnologie
• Rilevamento dei sistemi esterni a partire dai tag
• Estrazione delle tecnologie dagli argomenti posizionali
• Gruppi mappati sui tag

Viste, stili, temi e nodi di deployment vengono ignorati (Archyl ha un proprio livello visivo).

Il nome e la descrizione del workspace diventano il nome e la descrizione del progetto: vedi la sezione Nome e descrizione del progetto qui sopra. Un workspace senza nome può essere importato in un progetto esistente, ma non può crearne uno.

Workspace su più file (!include)

Un workspace suddiviso su più file, con !include systems/payments.dsl e simili, non può essere importato come file singolo, perché i file inclusi non sono disponibili per essere risolti. Carica invece l'intero workspace come .zip, nella scheda Structurizr DSL: i file dell'archivio vengono estratti e ogni !include viene risolto su di essi.

• Il punto di ingresso è workspace.dsl se l'archivio ne contiene uno, altrimenti il file .dsl meno annidato. Archyl indica quale file ha usato.
• I percorsi vengono risolti rispetto al file che contiene l'include, quindi gli include annidati funzionano.
• Includere una directory importa ogni file .dsl che si trova direttamente al suo interno, in ordine di nome.
• I cicli di inclusione vengono interrotti e segnalati, senza far fallire l'importazione.
• Le destinazioni remote (!include https://…) vengono rifiutate e i percorsi che escono dall'archivio vengono ignorati.

Tutto ciò che non può essere risolto diventa un avviso nel risultato dell'importazione: il resto del workspace viene comunque importato.

Limiti dell'archivio:

Vengono conservati solo i file .dsl, .md, .json, .yaml, .yml e .txt; tutto il resto dell'archivio viene ignorato.

Tramite l'API, invia l'archivio come multipart form data in un campo file, con un campo facoltativo entry che indica il punto di ingresso: POST /api/v1/dsl/validate-archive lo verifica, POST /api/v1/projects/{id}/dsl/import-archive lo importa in un progetto e POST /api/v1/dsl/import-project-archive crea un progetto a partire da esso. Lo strumento MCP import_dsl e la sincronizzazione dal repository leggono un singolo file e non risolvono !include.

Importazione LikeC4

Archyl è il primo strumento a importare file LikeC4. L'importer gestisce le caratteristiche specifiche di LikeC4:

• Tipi di elemento personalizzati dei blocchi specification mappati sui livelli C4
• Gerarchie di elementi annidati risolte in sistemi, container e componenti
• Proprietà technology: e description: (con o senza la sintassi con i due punti)
• Tag #hashtag convertiti in tag standard
• Rilevamento del tag #external per classificare i confini
• Più blocchi model uniti automaticamente
• Supporto per stringhe tra apici singoli e tripli

Importazione IcePanel JSON

Il formato di esportazione JSON di IcePanel è completamente supportato:

• Tipi di oggetto system, actor, app, store, component mappati sugli elementi C4
• Campo external: true per classificare i sistemi esterni
• modelConnections mappate sulle relazioni
• tagIds risolti nei nomi dei tag a partire dall'array tags
• Oggetti domain usati come nome del progetto

Importazione Backstage

Archyl importa il JSON del Software Catalog restituito dall'endpoint /api/catalog/entities di Backstage:

• Le entità System diventano sistemi Archyl (le collisioni tra namespace vengono disambiguate automaticamente)
• Le entità Component e Resource vengono raggruppate come container sotto il sistema a cui appartengono (tramite spec.system o la relazione partOf)
• I Component/Resource senza un sistema padre vengono raggruppati sotto un sistema sintetico Uncategorized
• I tipi di Resource sono mappati sui tipi di container Archyl: s3-bucket → file_storage; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database; kafka-topic, sqs-queue → message_queue; repository → library; tutto il resto → infrastructure
• I tipi di Component sono mappati così: service → service, cronworkflow → worker, website → web_app, library → library
• Le entità API vengono importate come Contratti API, conservando come contenuto lo spec.definition inline (OpenAPI / gRPC / GraphQL / AsyncAPI) e collegandole ai componenti provider/consumer
• dependsOn, consumesApi, producesTo, consumesFrom, versionedIn (e i loro inversi) vengono tradotte in relazioni Archyl
• metadata.namespace, spec.lifecycle e spec.type vengono esposti come tag
• Le entità User e Group vengono ignorate: il grafo di persone e team di Backstage non è un concetto C4

Per esportare il tuo catalogo:

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

Poi trascina entities.json nella scheda Backstage della finestra di importazione. Gli elenchi di risorse dei cataloghi più grandi possono produrre migliaia di container: controlla il risultato ed elimina ciò che non ti serve.

Importazione via MCP (agenti IA)

La stessa funzionalità di importazione è disponibile tramite lo strumento 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"

In questo modo gli agenti di programmazione IA (Claude Code, Cursor, Windsurf) possono importare file di architettura in modo programmatico.

Importazione in progetti esistenti

Puoi anche importare in un progetto esistente (non solo crearne di nuovi):

1. Apri il tuo progetto
2. Vai su Architecture as Code
3. Clicca su Importa
4. Seleziona il formato e carica il file

Gli elementi già esistenti vengono aggiornati; i nuovi elementi vengono creati.

Prossimi passi

• Panoramica API — Riferimento API completo per gli endpoint DSL
• Condivisione e incorporamento — Condividi diagrammi live
• Gestione delle release — Traccia i deployment nel tuo YAML
• Notifiche webhook — Ricevi notifiche quando l'architettura cambia