Esportazione e Importazione Progetti: La Tua Architettura, Completamente Portatile

Crediamo che la tua documentazione architetturale appartenga a te. Non chiusa in un formato proprietario, non intrappolata dietro un'API, non tenuta in ostaggio da un livello di abbonamento. Se hai investito tempo documentando i tuoi sistemi, container, componenti e relazioni, dovresti poter portare quel lavoro con te.

Oggi rendiamo concreta questa convinzione. Archyl ora supporta l'esportazione e importazione completa dei progetti.

Tutto in Un File

Quando esporti un progetto, ottieni un singolo file JSON contenente l'intero modello C4. Ogni sistema che hai definito, ogni container all'interno di quei sistemi, ogni componente, fino agli elementi di codice se hai modellato a quella profondità. Le relazioni che li collegano, con le loro descrizioni e annotazioni tecnologiche. Gli overlay visivi che hai creato per raggruppare e organizzare i tuoi diagrammi.

L'esportazione preserva il layout spaziale dei tuoi diagrammi. Hai dedicato tempo a posizionare gli elementi per comunicare la struttura chiaramente — l'API gateway a sinistra, i database a destra, i sistemi esterni in alto. Quella disposizione non è casuale; è parte di come comunichi la tua architettura. L'esportazione cattura tutto.

Il formato è JSON semplice, versionato e documentato. Aprilo in qualsiasi editor di testo e puoi leggerlo. Parsalo con uno script se vuoi fare qualcosa di personalizzato. Sono i tuoi dati in un formato che controlli.

Come Funziona l'Esportazione

Apri qualsiasi progetto a cui hai accesso, naviga all'opzione di esportazione e scegli il formato. Per la portabilità dei dati, seleziona JSON. Il file si scarica immediatamente — anche progetti grandi con centinaia di elementi si esportano in secondi.

Supportiamo anche esportazioni visive per diversi casi d'uso. SVG fornisce un formato vettoriale che puoi editare in Illustrator o incorporare nella documentazione. PNG fornisce un'immagine condivisibile. PDF crea un documento professionale. C'è anche un'opzione per combinare tutti e quattro i livelli C4 in un'unica esportazione completa.

Per l'automazione, l'endpoint API funziona esattamente come ci si aspetterebbe. Una richiesta GET a /projects/{id}/export restituisce il payload JSON completo. Integralo nella tua pipeline CI, programma backup settimanali o integralo con qualsiasi workflow tu abbia già.

L'Importazione Crea Progetti Nuovi

Quando importi un'architettura, Archyl crea un progetto completamente nuovo. Fornisci un nome e uno slug, opzionalmente selezioni un team e carichi il file JSON. Il sistema parsa l'esportazione, valida la struttura e ricrea ogni elemento con identificatori nuovi.

Questa è una scelta progettuale deliberata. L'importazione non fa merge in progetti esistenti né tenta di riconciliare i conflitti. Crea una copia pulita, indipendente dalla fonte. Il progetto originale continua invariato; il progetto importato inizia la sua propria vita.

Il processo di importazione gestisce la complessità del rimappaggio degli ID in modo trasparente. L'esportazione contiene gli UUID originali di quando gli elementi sono stati creati. L'importazione genera nuovi UUID per tutto preservando le relazioni tra gli elementi. Un container che apparteneva a un sistema specifico appartiene ancora a quel sistema. Una relazione che collegava due componenti li collega ancora. La struttura è identica; cambiano solo gli identificatori.

Se una relazione nell'esportazione fa riferimento a un elemento che non esiste — forse da un'esportazione parziale o un file corrotto — l'importazione registra un avviso e continua. Otterrai tutto ciò che è stato possibile importare, con visibilità su ciò che è stato saltato.

Casi d'Uso Reali

Una società di consulenza con cui lavoriamo usa l'esportazione per consegnare documentazione architetturale ai clienti. Modellano il sistema del cliente in Archyl, lo raffinano attraverso discovery e documentazione manuale, poi esportano il risultato finale. Il cliente riceve un file JSON che può importare nella propria istanza Archyl o semplicemente archiviare come record dell'incarico.

Un team di piattaforma enterprise esporta la propria architettura settimanalmente verso un sistema di backup interno. Se qualcosa va storto con la documentazione principale, possono ripristinare dall'ultima esportazione. Il formato JSON significa che il backup è leggibile e verificabile, non un blob binario opaco.

Una startup ha usato l'esportazione durante un'acquisizione. L'azienda acquirente aveva bisogno di capire l'architettura di sistema del target. Invece di programmare settimane di riunioni di trasferimento delle conoscenze, il team ha esportato il proprio progetto Archyl e condiviso il file. Gli acquirenti l'hanno importato, esplorato interattivamente, e sono arrivati alle discussioni di integrazione con una comprensione reale di ciò che stavano comprando.

I team di sviluppo usano l'esportazione come snapshot architetturali. Dopo un rilascio importante, esportano lo stato corrente e fanno commit del file JSON insieme al codice. Mesi dopo, quando qualcuno chiede "com'era l'architettura prima della migrazione ai microservizi?", la risposta è a un git checkout di distanza.

Cosa Viene Esportato

L'esportazione include la gerarchia C4 completa. Sistemi al livello superiore, con container annidati all'interno, componenti dentro i container ed elementi di codice dentro i componenti. Ogni elemento porta i suoi metadati completi: nome, descrizione, tipo, stack tecnologico, tag, coordinate di posizione e qualsiasi stile personalizzato.

Le relazioni sono esportate con entrambi gli endpoint specificati, insieme al loro tipo, descrizione e proprietà visive come le posizioni delle etichette. Il processo di importazione le mappa sugli elementi appena creati, mantenendo l'esatta struttura di connessione.

Gli overlay — i raggruppamenti visivi che crei per organizzare diagrammi complessi — sono inclusi con le loro posizioni, dimensioni, colori e gli elementi che contengono.

Cosa non viene attualmente esportato: ADR, documentazione di progetto, flussi utente e connessioni ai repository. L'esportazione si concentra sul modello C4 stesso — sistemi, container, componenti, codice e le loro relazioni. Stiamo considerando di espandere l'ambito nelle prossime release in base a ciò che gli utenti ci dicono di aver bisogno.

Nessun Lock-In, Nessun Trucco

Il formato di esportazione usa la versione "1.0" oggi. Man mano che aggiungiamo funzionalità, aggiorneremo il formato mantenendo la compatibilità all'indietro. Un'esportazione che crei oggi si importerà correttamente tra anni, anche man mano che Archyl evolve.

Non siamo interessati a intrappolare i tuoi dati. Siamo interessati a essere abbastanza utili da farti scegliere di restare. Esportazione e importazione sono il nostro impegno verso questa filosofia. Se Archyl smette di essere lo strumento giusto per te, prendi la tua architettura e vai. Se un concorrente costruisce qualcosa di meglio, abbiamo reso facile il passaggio. La pressione è su di noi per continuare a meritare la tua fiducia.

Per Iniziare

Esportazione e importazione sono disponibili su tutti i piani, incluso il Gratuito. Nessuna restrizione artificiale, nessun gioco del tipo "l'esportazione è una funzionalità premium".

Per esportare: apri qualsiasi progetto, trova il pulsante esporta, seleziona JSON e salva il file.

Per importare: dalla lista dei tuoi progetti, clicca Importa, carica un file JSON, dai un nome al tuo nuovo progetto e conferma.

La tua documentazione architetturale è tua. Ora puoi portarla ovunque.

Vuoi saperne di più su cosa puoi documentare in Archyl? Leggi la nostra Introduzione al Modello C4 o scopri come la Discovery Architetturale con AI può mappare automaticamente i tuoi sistemi esistenti.