Scegli come iniziare

Un progetto Archyl contiene un modello C4 del tuo software: sistemi, container, componenti e codice, e le relazioni tra loro. Ci sono quattro modi per riempirlo. Si possono combinare, e nessuno ti vincola.

Qualunque cosa tu scelga, i passi successivi sono gli stessi: collegare i tuoi agenti di programmazione e mantenere il modello allineato al codice.

Disegnala nell'app

Crea un progetto dalla dashboard, poi aggiungi sistemi, container e relazioni sul canvas. La Guida Rapida ti accompagna passo dopo passo.

Disegnare è il punto di partenza giusto per un sistema che non esiste ancora, o per abbozzare il contesto prima di scrivere codice. Puoi passare al codice in seguito: archyl dsl pull scrive ciò che hai disegnato in archyl.yaml.

Scoprila con l'IA

La scoperta tramite IA legge un repository collegato e propone sistemi, container, componenti, relazioni e tecnologie. Nulla entra nel modello finché non lo approvi.

Dall'app: collega il repository in Impostazioni Progetto › Integrazione Git (vedi Integrazione Git), avvia una scoperta, poi rivedi ciò che ha trovato.

Dal terminale, nella radice del repository:

archyl login
archyl init --new

init --new crea il progetto, collega il repository a partire dal suo remote git, esegue la scoperta sotto i tuoi occhi, apre la revisione, disegna il risultato e propone di collegare i tuoi agenti di programmazione. Flag utili: --name, --team, --branch, --provider per un remote self-hosted (github_enterprise, gitlab_private, gitea) e --yes per accettare tutti i valori predefiniti. Vedi la guida alla CLI.

La scoperta gestisce i monorepo: riconosce apps/, packages/, services/ e libs/, e associa ogni servizio a un container.

Scrivila come codice

Descrivi l'architettura in un archyl.yaml nella radice del repository e inviala con un push. Il formato del file è in Architettura come Codice.

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 file minimo:

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

Gli elementi vengono abbinati per nome. Un push crea ciò che è nuovo e aggiorna ciò che è cambiato, e non elimina mai nulla: un elemento presente solo in Archyl resta, e archyl dsl diff lo elenca come «only in Archyl».

Il tuo agente di programmazione può scrivere la prima versione: esegui archyl setup, poi chiedigli di descrivere il repository in archyl.yaml seguendo lo schema. Resta comunque un file che spetta a te rivedere.

Per mantenere allineati il file e il modello, fai commit di archyl.yaml e invialo dalla CI con la GitHub Action, oppure usa Sincronizza ora in Impostazioni Progetto › Architettura come Codice. archyl dsl diff --exit-code fa fallire un job di CI quando differiscono.

Importala da un altro strumento

Dall'elenco dei progetti, clicca su Importa progetto e scegli il formato: Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON o Backstage JSON. Un workspace Structurizr suddiviso in file !include può essere caricato come zip. I dettagli, e dove ogni formato conserva il nome del progetto, sono in Importazione di progetti.

Guida per un monorepo

Questo è il percorso via codice dall'inizio alla fine per un monorepo, senza scoperta tramite IA:

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

1. Crea il progetto e collega il repository. Dalla radice del monorepo:

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

Questo scrive .archyl.json, che collega il repository al progetto. Fanne il commit: non contiene alcun segreto.

2. Modella un sistema con un container per ogni deployable. App e servizi diventano container. Un pacchetto condiviso come packages/ui di solito non è un container a sé: descrivilo come componente dei container che lo usano, o lascialo fuori.

3. Dai a ogni container il nome della sua cartella. È ciò che permette a archyl brief, where, check, impact e all'hook Guard di capire a quale elemento appartiene un file modificato: un file appartiene a un elemento quando una delle cartelle del suo percorso ha il nome dell'elemento. Il confronto ignora maiuscole, spazi e punteggiatura, oltre a una parola finale come API, Service o Worker, quindi Orders Service corrisponde a services/orders/… e Payments API a services/payments/….

4. Scegli un file o più file. Un singolo archyl.yaml nella radice è la soluzione più semplice. Per un monorepo grande, dai a ogni servizio un proprio file accanto al suo codice e includili dalla radice, così ogni team modifica la propria parte:

# 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

I percorsi di include sono relativi al file che li dichiara, e le relazioni possono puntare a elementi in uno qualsiasi dei file. Le regole sono in Include.

5. Fai push e controlla.

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

Se where segnala un file come non abbinato, rinomina il container come la sua cartella e fai di nuovo push.

6. Mantienilo aggiornato. Fai commit di archyl.yaml e dei file inclusi. Fai push dalla CI quando ci sono modifiche, oppure usa Sincronizza ora, che recupera dal repository anche i file inclusi.

E poi, mettila al lavoro

Una volta che il modello esiste:

• Collega i tuoi agenti di programmazione con archyl setup (Claude Code, Cursor, VS Code, Codex) o dalla dashboard. Così chiamano plan, brief e l'harness prima di modificare il codice.
• Controlla le modifiche rispetto al modello con archyl check e archyl review in CI. Vedi la guida alla CLI.
• Fai conoscere il sistema a persone e agenti con archyl tour: una visita guidata alle parti da conoscere per prime, con i file da leggere. archyl tour --markdown > ONBOARDING.md la mette per iscritto.
• Esploralo con archyl map, archyl diagram <element> o il canvas nell'app.

Combinare i percorsi

• Scoprire, poi gestire come codice: esegui una scoperta, approvala, poi usa archyl dsl pull e fai commit di archyl.yaml da quel momento in poi.
• Scrivere come codice, poi scoprire: una scoperta propone solo ciò che il modello non ha già, quindi può completare i componenti sotto i container che hai scritto. Rivedila come qualsiasi altra scoperta.
• Disegnare nell'app e fare push dal codice: entrambi modificano lo stesso modello. Un push aggiorna ciò che il file descrive e lascia intatto il resto.