Mantenere aggiornata la documentazione tecnica è una delle attività più difficili nello sviluppo software. Diagrammi e schemi dell’architettura tendono infatti a diventare rapidamente obsoleti, soprattutto nei progetti in continua evoluzione. LiveArch affronta questo problema con un approccio completamente automatico: analizza il codice sorgente e genera una rappresentazione grafica dell’applicazione che si aggiorna in tempo reale a ogni modifica.
L’obiettivo del progetto è eliminare la necessità di disegnare manualmente l’architettura o di descrivere il funzionamento dell’applicazione a strumenti esterni. Tutte le informazioni vengono ricavate direttamente dal repository, offrendo una vista fedele della struttura del software e delle relazioni tra i vari componenti.
Il risultato viene salvato come un singolo file HTML interattivo, denominato .visualarch.html, che può essere aperto in qualsiasi browser e condiviso con il resto del team senza richiedere servizi online o piattaforme cloud.
Diagrammi sempre aggiornati grazie all’analisi automatica del codice
LiveArch monitora costantemente il progetto e reagisce automaticamente ogni volta che uno sviluppatore salva un file. Dopo una breve attesa di circa 350 millisecondi per evitare analisi ripetute durante modifiche ravvicinate, lo strumento riesamina l’intero repository e rigenera il diagramma.
L’intero flusso di lavoro è completamente automatizzato:
- lo sviluppatore salva un file nel proprio editor;
- LiveArch rileva la modifica;
- viene eseguita una nuova analisi dell’intero progetto;
- il file .visualarch.html viene riscritto;
- un collegamento WebSocket aggiorna immediatamente il browser aperto;
- il diagramma viene ridisegnato evidenziando in verde i nuovi componenti aggiunti.
A differenza di strumenti che si affidano a descrizioni manuali o a interpretazioni dell’architettura, LiveArch legge direttamente gli elementi presenti nel codice. Analizza importazioni, percorsi delle applicazioni, modelli Prisma e altre informazioni strutturali, distinguendo chiaramente le relazioni certe da quelle dedotte. I collegamenti realmente individuati nel codice vengono rappresentati con linee continue, mentre quelli inferiti sono mostrati con linee tratteggiate.
Supporto per numerosi linguaggi e massima privacy
Uno degli aspetti più interessanti di LiveArch è il supporto per numerosi linguaggi e framework moderni. Lo strumento è compatibile con progetti JavaScript e TypeScript, compreso Next.js App Router, oltre a Python, Go, Rust, Prisma e repository organizzati come monorepo.
Un’altra caratteristica importante riguarda la privacy. Tutta l’elaborazione avviene esclusivamente sul computer dello sviluppatore: nessun file viene inviato a server remoti e nessuna parte del codice lascia la macchina locale. Questo rende LiveArch particolarmente interessante anche per aziende e team che lavorano su software proprietario o progetti soggetti a requisiti di riservatezza.
Il diagramma prodotto è inoltre facilmente condivisibile. Essendo un semplice file HTML interattivo, può essere incluso nel repository insieme al codice e aggiornarsi automaticamente durante lo sviluppo. Il progetto permette anche di aggiungere un badge nel file README per indicare la presenza della documentazione architetturale aggiornata, offrendo ai collaboratori un accesso immediato alla struttura dell’applicazione.
Per gli sviluppatori che lavorano su applicazioni complesse o in continua evoluzione, LiveArch rappresenta una soluzione pratica per mantenere una documentazione tecnica sempre coerente con il codice sorgente, riducendo il rischio di informazioni obsolete e semplificando la comprensione dell’architettura del progetto.
Installare LiveArch
LiveArch è disponibile per pc e server Linux attraverso npm per maggiori informazioni basta consultare la pagina ufficiale Github del progetto. Abbiamo testato LiveArch su Ubuntu 26.04 LTS.
