3.600+ nodi. 7.100 connessioni. 249 community.
Questi non sono numeri di un social network. Sono i numeri del codice sorgente dei nostri due prodotti SaaS, Ambra e Prisma, trasformati in knowledge graph.
L’idea è semplice: prendere una codebase, analizzare ogni file e ogni dipendenza, e costruire una mappa. Non una mappa astratta da diagramma UML che nessuno aggiorna. Una mappa che si genera dal codice reale, che riflette lo stato attuale dell’architettura, e che un coding agent può consultare prima di mettere le mani nel codice.
Come funziona: da file a grafo in una riga
Il principio è lineare: ogni file del progetto diventa un nodo. Ogni dipendenza tra file (un import, un export, una chiamata cross-module) diventa un arco. Un algoritmo di community detection analizza la densità delle connessioni e raggruppa i nodi in cluster: file che lavorano insieme finiscono nella stessa community.
Nessuno definisce i cluster a mano. L’algoritmo li trova da solo, basandosi esclusivamente sulla struttura delle dipendenze. E quando guardi i risultati, ogni cluster corrisponde a un modulo reale del prodotto.
I numeri dei nostri due prodotti
Abbiamo applicato questo processo a entrambi i nostri prodotti SaaS: Ambra (piattaforma di customer management AI) e Prisma (CRM con agenti AI integrati).
Ambra
Prisma
Il knowledge graph di Ambra
Nel grafo di Ambra ogni pallino rappresenta un file, il colore indica la community di appartenenza e la dimensione è proporzionale al numero di connessioni.
Sulla destra, la lista delle community con i file principali: SubaccountManager.tsx, WarmupDashboard.tsx, Settings.tsx nella community 75; index.ts, processMessage(), getNotificationAdapters() nella community 10; types.ts, CRMAdapter, SyncResult nella community 12.
Il knowledge graph di Prisma
Il grafo di Prisma mostra una struttura diversa. Le community hanno nomi che riflettono i moduli del prodotto: Cron Jobs & Outbound (73 file), Dashboard & Reporting (48), Conversations UI (44), WhatsApp & Events (22), D1 Client Resolution (24), Bot Commands (19). La visualizzazione in dark mode evidenzia chiaramente i cluster e le connessioni inter-community.
Lezione 1: l’architettura emerge da sola
Questo è il risultato più sorprendente. I cluster non li abbiamo definiti noi: li ha trovati l’algoritmo, analizzando esclusivamente i pattern di import/export tra file.
Su Ambra emergono community come CRMAdapter, CalendarAdapter, ChatThread.
Su Prisma compaiono WhatsApp & Events, Conversations UI, Bot Commands.
Ogni community corrisponde a un modulo reale del prodotto, a un pezzo di business logic che ha senso anche letto da chi non conosce il codice.
Quando la struttura del codice riflette la struttura del business, è un buon segno. Significa che l’architettura non è cresciuta per accidente ma ha mantenuto una coerenza interna. E quando non la riflette, il grafo te lo mostra subito: file orfani, community ibride che mescolano responsabilità diverse, accoppiamenti anomali.
Lezione 2: i nodi centrali sono punti di fragilità
Ogni grafo ha i suoi hub: file con un numero sproporzionato di connessioni in entrata e in uscita. Questi non sono necessariamente i file più importanti in termini di business logic, ma sono quelli dove un bug si propaga più velocemente.
Un types.ts importato da 40 file è un moltiplicatore di rischio.
Un index.ts che riesporta metà del progetto è un collo di bottiglia architetturale.
Un file di utility con 30 dipendenti è un candidato primo per un refactoring.
Identificarli prima di un refactoring cambia completamente l’approccio. Non stai più lavorando alla cieca: sai esattamente dove il rischio è più alto, quali file toccare con cautela e quali possono essere modificati in sicurezza.
Lezione 3: con i coding agent, il grafo diventa una mappa operativa
Qui il knowledge graph smette di essere un esercizio accademico e diventa uno strumento di lavoro quotidiano.
Quando un coding agent come Claude Code deve intervenire su una codebase, il primo passo è sempre lo stesso: capire dove mettere le mani. Su un progetto da 2.000 file, questo significa leggere centinaia di file per costruirsi un modello mentale dell’architettura. Ogni file letto è un consumo di token, e ogni token consumato per l’esplorazione è un token in meno disponibile per il lavoro vero.
Con il knowledge graph, l’agente parte con una mappa già costruita.
Sa che processMessage() è nel cuore della community 10 di Ambra, connessa a notifiche e adapter.
Sa che toccare types.ts nella community 12 significa potenzialmente impattare CRMAdapter e SyncResult.
Sa che Cron Jobs & Outbound in Prisma è la community più grande, con 73 file collegati tra loro.
Risultato pratico: meno token bruciati per l’esplorazione, meno allucinazioni perché l’agente non deve inferire la struttura, e modifiche più precise perché conosce il raggio di impatto prima di scrivere una riga di codice. Se poi combini il knowledge graph con skill dedicate per testing e validazione, ottieni modifiche precise al primo colpo.
Oltre la mappa: come il grafo guida le decisioni di refactoring
Il knowledge graph non serve solo ai coding agent. È uno strumento decisionale per qualsiasi team di sviluppo.
Tre scenari concreti in cui lo usiamo internamente:
Prioritizzazione del refactoring: invece di scegliere cosa rifattorizzare in base all’intuizione, guardiamo i nodi con più connessioni. Un file con 50 dipendenti che viene toccato spesso è un candidato oggettivo per la semplificazione, indipendentemente da quanto “brutto” sia il codice di altri file meno connessi.
Onboarding di nuovi sviluppatori: mostrare il grafo a un nuovo membro del team vale più di 10 pagine di documentazione. In 30 secondi vede l’architettura reale, identifica i moduli principali e capisce dove si concentra la complessità.
Analisi di impatto pre-merge: prima di fare merge di una feature branch significativa, sovrapponiamo i file modificati al grafo. Se una PR tocca file in 5 community diverse, è un segnale che forse la modifica ha un raggio d’azione troppo ampio e va spezzata.
Come costruire il tuo knowledge graph
Il tool che abbiamo usato è Graphify, un progetto open source che trovate su GitHub (link nel primo commento del post LinkedIn originale). Il processo è automatizzato: punta il tool alla root del progetto, lancia l’analisi e in pochi secondi hai il grafo completo con community detection.
Non servono configurazioni complesse. Funziona su qualsiasi codebase TypeScript/JavaScript e produce una visualizzazione interattiva dove puoi esplorare le community, cercare file specifici e ispezionare le connessioni di ogni nodo.
Se stai usando coding agent per lo sviluppo, il knowledge graph non è un nice-to-have. È l’equivalente di dare a un chirurgo una risonanza magnetica prima di operare, invece di chiedergli di tagliare e sperare di trovare il problema.
Due prodotti, due grafi, una lezione
Ambra e Prisma sono prodotti diversi, con architetture diverse e finalità diverse. Ma il knowledge graph racconta la stessa storia in entrambi i casi: la struttura del codice non mente.
Se l’architettura è pulita, le community emergono come moduli distinti e coerenti. Se ci sono problemi strutturali, il grafo li evidenzia prima che diventino bug in produzione. E se stai delegando lo sviluppo a un coding agent, dargli una mappa del territorio è la differenza tra un intervento chirurgico e una passeggiata alla cieca.
I numeri parlano chiaro: 3.600 nodi, 7.100 connessioni, 249 community tra due prodotti. Non è la dimensione che conta, ma quello che i numeri rivelano sulla salute della tua codebase.