Backstage vs Archyl: due approcci alla documentazione dell'architettura

Se stai valutando strumenti per la documentazione dell'architettura, probabilmente hai guardato Backstage. È open source, è sostenuto da Spotify e ha un ecosistema di plugin che copre di tutto, dalla CI/CD alla gestione dei costi. Uno di quei plugin gestisce i diagrammi C4.

Archyl adotta l'approccio opposto. Non è un developer portal. Non gestisce pipeline di CI né cataloghi di servizi. Fa una cosa sola: documentazione dell'architettura con il modello C4, e la fa in profondità.

Questo non è un articolo su "quale strumento è migliore". Servono a scopi diversi. Ma se ciò che ti serve davvero è la documentazione dell'architettura, le differenze contano. Vediamole una per una.

La filosofia di fondo

Backstage è un framework per developer portal. Il suo compito è riunire in un'unica piattaforma interna tutti gli strumenti, i servizi e la documentazione che un team di sviluppo usa. La documentazione dell'architettura è uno dei tanti plugin disponibili: una funzionalità all'interno di un ecosistema più ampio.

Archyl è una piattaforma costruita appositamente per la documentazione dell'architettura. L'intero prodotto esiste per modellare, visualizzare, analizzare ed evolvere l'architettura software con il modello C4. Ogni funzionalità torna a quell'unico scopo.

Questa differenza di ambito determina tutto il resto.

Supporto al modello C4

Backstage

Il modello di entità di Backstage include Components, APIs, Resources, Systems, Domains, Groups e Users. Corrisponde a grandi linee ai livelli 1 e 2 del C4, cioè sistemi e container. Ma la corrispondenza è approssimativa, non precisa.

Il plugin C4 per Backstage (backstage-plugin-c4-model) genera diagrammi dalle entità esistenti del catalogo. Supporta le viste System Context e Container. Non c'è supporto nativo per il livello 3 del C4 (Component) né per il livello 4 (Code). Se le tue esigenze di modellazione scendono sotto il livello dei container, sbatti contro un muro.

Il catalogo stesso è basato su YAML. Ogni entità è definita in file catalog-info.yaml, di solito committati insieme al codice. L'architettura è quindi definita in file di configurazione, non in uno strumento visuale, e si importa in un modello C4 con un solo upload.

Archyl

Archyl implementa nativamente tutti e quattro i livelli C4:

• Livello 1 — System Context: sistemi, sistemi esterni e persone
• Livello 2 — Container: applicazioni, servizi, database, code di messaggi, cache e altro
• Livello 3 — Component: controller, servizi, repository, handler, middleware, modelli
• Livello 4 — Code: classi, interfacce, funzioni, metodi, enum, costanti

Ogni livello ha i propri tipi di nodo, stili visivi e metadati. Puoi scendere da un sistema ai suoi container, da un container ai suoi componenti, da un componente ai suoi elementi di codice, tutto nello stesso diagramma interattivo. Le relazioni tra elementi a qualsiasi livello sono cittadini di prima classe, con connessioni tipizzate (uses, depends_on, calls, reads_from, writes_to, ecc.).

La differenza: Backstage ti dà un catalogo con le viste C4 aggiunte sopra. Archyl ti dà un ambiente di modellazione C4 completo in cui rappresentare l'intera architettura a qualsiasi livello di dettaglio.

Visualizzazione

Backstage

Il plugin C4 genera diagrammi statici o semi-interattivi dai dati del catalogo. La visualizzazione dipende dall'implementazione specifica del plugin: alcuni usano PlantUML, altri Structurizr, altri ancora disegnano nel browser. Ma l'esperienza è fondamentalmente in sola lettura. Guardi diagrammi generati da definizioni YAML. Non interagisci con loro.

Non c'è manipolazione del canvas, niente posizionamento drag-and-drop, niente collaborazione in tempo reale sui diagrammi. Per cambiare la rappresentazione dell'architettura, modifichi file YAML e aspetti che il catalogo si aggiorni.

Archyl

Archyl offre un canvas completamente interattivo costruito su React Flow. Puoi:

• Trascinare e posizionare qualsiasi elemento del diagramma
• Disegnare relazioni tra elementi direttamente sul canvas
• Navigare tra i livelli C4 entrando in sistemi, container e componenti
• Vedere in tempo reale i cursori dei colleghi che lavorano sullo stesso diagramma
• Usare l'auto-layout per disporre gli elementi automaticamente, oppure posizionarli a mano
• Applicare overlay per raggruppare visivamente elementi correlati
• Passare dal tema chiaro a quello scuro sul diagramma

Il canvas è lo spazio di lavoro principale, non un artefatto generato. Ogni modifica che fai sul diagramma si riflette all'istante.

Scoperta tramite IA

Backstage

Backstage non ha una scoperta dell'architettura basata sull'IA integrata. Per popolare il catalogo crei a mano i file catalog-info.yaml per ogni servizio, oppure usi entity provider che importano da fonti esterne (Kubernetes, GitHub, ecc.). Alcuni plugin della community aggiungono capacità di IA, ma non c'è un'analisi nativa dell'architettura a partire dal codice.

Se hai 200 servizi e nessuno ha un file catalog-info.yaml, stai scrivendo 200 file YAML a mano, oppure costruendo strumenti personalizzati per generarli.

Archyl

Archyl include una scoperta tramite IA integrata che si collega al tuo repository Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea o repository locali), legge il codebase e genera automaticamente un modello C4 completo.

La pipeline di scoperta:

1. Si collega al tuo repository
2. Analizza file sorgente, codice infrastrutturale e configurazione
3. Identifica sistemi, container, componenti e le loro relazioni
4. Rileva le dipendenze dai manifest dei pacchetti
5. Genera una proposta di modello C4 con auto-layout
6. Presenta il risultato per la tua revisione e approvazione

Puoi approvare, modificare o rifiutare qualsiasi parte del modello generato. L'IA fa il lavoro pesante della mappatura iniziale dell'architettura; tu metti il giudizio.

Il sistema comprende Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, YAML di Kubernetes, chart Helm e altro.

Architecture Decision Record

Backstage

In Backstage gli ADR sono di solito gestiti con il plugin ADR, che legge i file markdown degli ADR da un repository. Li mostra nell'interfaccia di Backstage, spesso nel formato MADR (Markdown Architectural Decision Records). Gli ADR vivono in Git come file markdown.

Non c'è alcun collegamento tra ADR ed entità del catalogo. Un ADR sulla scelta di PostgreSQL rispetto a MongoDB sta in una cartella /docs/adr/, senza alcuna connessione diretta con il container del database a cui si riferisce.

Archyl

In Archyl gli ADR sono oggetti di prima classe collegati direttamente agli elementi C4. Quando crei un ADR, puoi associarlo a sistemi, container, componenti o elementi di codice specifici. Questo significa che:

• Apri un container sul diagramma e vedi i suoi ADR correlati
• Sfogli gli ADR e vedi esattamente quali elementi dell'architettura riguardano
• Capisci il ragionamento dietro le scelte architetturali nel loro contesto

Gli ADR supportano stati (proposed, accepted, deprecated, superseded) e contenuti markdown ricchi, con sezioni strutturate per contesto, decisione e conseguenze.

Documentazione

Backstage

Il sistema TechDocs di Backstage converte file markdown (di solito con MkDocs) in documentazione consultabile all'interno del portale. È basato su markdown e su Git. La documentazione viene visualizzata bene e supporta la ricerca.

Però TechDocs è documentazione generica, non documentazione dell'architettura. Non c'è alcun collegamento strutturale tra i documenti e il modello di architettura. Una pagina su "Architettura di autenticazione" non è collegata al sistema di autenticazione sul diagramma.

Archyl

Il sistema di documentazione di Archyl è integrato con il modello di architettura. Gli elementi di documentazione possono essere collegati agli elementi C4, organizzati in cartelle e consultati nel contesto, accanto ai diagrammi. Quando guardi un sistema o un container, la documentazione correlata è visibile nel pannello laterale.

Non si tratta di sostituire gli strumenti di documentazione generica. Si tratta di far vivere la documentazione dell'architettura accanto all'architettura che descrive.

Analisi d'impatto

Backstage

Backstage non ha alcuna capacità di analisi d'impatto. Se vuoi capire cosa si rompe quando deprechi un servizio, tracci a mano le dipendenze attraverso il catalogo. Non c'è analisi automatica a monte e a valle, niente punteggio di rischio, niente simulazione what-if.

Alcune organizzazioni costruiscono script o plugin personalizzati per analizzare le relazioni del catalogo, ma non c'è nulla di integrato.

Archyl

L'Impact Radar di Archyl offre un'analisi d'impatto completa direttamente sul diagramma. Fai clic destro su qualsiasi elemento e vedi subito:

• Dipendenti a monte e dipendenze a valle, organizzati per grado (1, 2, 3 salti)
• Punteggio di rischio calcolato dai dipendenti a monte, dalla portata a valle, dai figli strutturali e dal rapporto di accoppiamento
• Percorso critico che evidenzia la catena di dipendenze più lunga
• Dipendenze tra progetti quando usi l'Architettura Globale
• Flussi interessati, incrociati con i percorsi utente documentati
• Simulazione what-if che mostra esattamente cosa si rompe se un elemento viene rimosso

L'analisi gira in modo deterministico sul grafo delle relazioni. Niente congetture, niente riunioni per capire chi è coinvolto.

Gestione delle modifiche

Backstage

Le modifiche al catalogo di Backstage passano da Git. Crei una PR che modifica catalog-info.yaml, la fai revisionare e fai il merge. È il workflow Git standard: non c'è una gestione delle modifiche specifica per l'architettura.

La revisione avviene in GitHub/GitLab, non nel contesto dell'architettura. I revisori vedono diff YAML, non diff visivi di come cambia l'architettura.

Archyl

Archyl ha Architecture Change Request dedicate: un workflow simile alle pull request, pensato apposta per le modifiche all'architettura. Proponi modifiche al modello C4, i revisori vedono esattamente cosa viene aggiunto, modificato o rimosso, e la modifica passa da un processo di approvazione prima di essere applicata.

Questo porta governance nell'evoluzione dell'architettura senza costringere tutto a passare da file YAML e diff Git.

Collaborazione

Backstage

Backstage è un portale web. Più persone possono accedervi contemporaneamente, ma non c'è collaborazione in tempo reale sull'architettura in sé. Consulti il catalogo ognuno per conto suo. Niente cursori live, niente indicatori di presenza, niente modifica concorrente.

Archyl

Archyl offre collaborazione in tempo reale sui diagrammi C4:

• Cursori live che mostrano dove si trovano i colleghi sul canvas
• Indicatori di presenza che mostrano chi sta guardando il diagramma
• Tracciamento del focus sugli elementi, così vedi su quali elementi stanno lavorando i colleghi
• Modifica concorrente con risoluzione dei conflitti

Questo vale sia per i diagrammi C4 di progetto sia per la vista Architettura Globale.

Dati operativi live

Una delle sorprese più grandi quando si scopre Archyl è il Marketplace. La documentazione dell'architettura non è fatta solo di diagrammi statici: Archyl si collega agli strumenti che i tuoi team usano già e mostra dati live direttamente sulla tua architettura.

Backstage

Qui il punto di forza di Backstage è il suo ecosistema di plugin. Ci sono plugin per quasi tutto: stato della CI/CD, dashboard di monitoraggio, tracciamento dei costi, stato di Kubernetes e altro. Ma questi plugin vivono in pagine proprie all'interno del portale. Non sono collegati alla vista dell'architettura. Vedi lo stato della CI/CD di un servizio nella sua pagina del catalogo, ma non sul diagramma C4 dove quel servizio vive nel contesto di tutto ciò da cui dipende.

Archyl

Il Marketplace di Archyl offre integrazioni che portano dati live, sotto forma di widget, direttamente sulle dashboard della tua architettura:

• CI/CD: stato dei workflow GitHub Actions, PR aperte, alert di Dependabot, scansioni di sicurezza. Stato delle pipeline GitLab, merge request, report sulle vulnerabilità, alert SAST/DAST. Stato delle applicazioni Argo CD e tracciamento dei deployment.
• Osservabilità: dashboard Datadog incorporate, query sulle metriche, stato dei monitor. Query istantanee e su intervalli di Prometheus, salute dei target. Tracciamento degli errori con Sentry.
• Qualità del codice: stato del quality gate di SonarQube, misure del codice, issue, security hotspot e rating.
• Gestione degli incidenti: stato degli incidenti PagerDuty, incidenti attivi, turni di reperibilità, salute dei servizi.

I widget si aggiornano automaticamente e possono essere limitati a tre livelli: intera organizzazione, singolo progetto o un elemento C4 specifico. Un container che rappresenta il tuo servizio di pagamento può mostrare lo stato della build su GitHub Actions, il quality gate di SonarQube, le metriche di salute di Datadog e il turno di reperibilità su PagerDuty, tutto in un unico posto.

Così la documentazione dell'architettura passa da riferimento statico a vista operativa viva. Il diagramma non mostra solo com'è fatto il tuo sistema, ma anche come sta andando in questo momento.

Oltre le basi

Qualche altro ambito in cui i due approcci divergono:

Quando scegliere cosa

Scegli Backstage se ti serve un developer portal unificato che riunisca documentazione, CI/CD, catalogo dei servizi, gestione dei costi e decine di altri aspetti in un'unica piattaforma interna. La documentazione dell'architettura è un tassello di quel puzzle, e una vista C4 ad alto livello basta per le tue esigenze.

Scegli Archyl se la documentazione dell'architettura è una preoccupazione primaria, ma non vuoi sacrificare la visibilità operativa per ottenerla. Archyl va in profondità sul modello C4 (tutti e 4 i livelli), sui diagrammi interattivi, sulla scoperta tramite IA, sull'analisi d'impatto e sulla governance delle modifiche, mentre le integrazioni del suo Marketplace portano stato della CI/CD, monitoraggio, qualità del codice e dati sugli incidenti direttamente sulla tua architettura. Ottieni strumenti di architettura mirati senza perdere il contesto operativo che Backstage fornisce con il suo ecosistema di plugin.

Possono anche convivere. Archyl si occupa della modellazione dettagliata dell'architettura, dell'analisi e della visibilità operativa riferita all'architettura. Backstage si occupa della developer experience più ampia: onboarding, ricerca nel catalogo, dashboard dei costi e documentazione generale. Il modello di architettura in Archyl può orientare ciò che documenti nel catalogo dei servizi di Backstage, senza che nessuno dei due strumenti sostituisca l'altro.

In sintesi

Backstage è un framework di piattaforma che assembli a partire dai plugin. È potente, flessibile e risolve il problema della frammentazione della developer experience. Ma le sue capacità di documentazione dell'architettura si limitano a ciò che possono offrire i plugin C4 basati sul catalogo: in genere i livelli 1 e 2, viste statiche, niente IA, niente analisi d'impatto, niente collaborazione in tempo reale sui diagrammi.

Archyl è uno strumento mirato che va in profondità sull'architettura. Copre l'intero modello C4, la scoperta tramite IA, l'analisi d'impatto, la governance delle modifiche e la collaborazione in tempo reale, e si collega ai tuoi strumenti di CI/CD, osservabilità, qualità del codice e gestione degli incidenti, così la tua architettura resta ancorata alla realtà operativa. Non è un developer portal, ma è molto più di una documentazione statica.

La tua architettura merita più di una voce in un catalogo.

Nuovo al modello C4? Inizia dalla nostra guida al modello C4. Stai già modellando? Prova la scoperta dell'architettura con l'IA per avviare il tuo primo progetto dal codice, oppure esplora l'Impact Radar per capire una modifica prima di farla.