tempo di lettura : 12 minutes

Il tuo codebase cresce. Le dipendenze tra i moduli si moltiplicano. La documentazione dell’architettura diventa obsoleta prima ancora di essere scritta. E se il tuo build Gradle potesse automaticamente generare diagrammi aggiornati a partire dalla struttura reale del codice? Questo è esattamente ciò che fa la pipeline Graphify + PlantUML Gradle Plugin :`graphify . --no-viz`estrae il Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`le trasforma in diagrammi PlantUML. Zero LLM, zero manuale, 100% deterministico.

indice

[]

Il problema : dei diagrammi sempre in ritardo rispetto al codice

Ogni progetto che supera qualche migliaio di linee conosce questo sintomo :

  1. Si disegna un diagramma di architettura all’inizio del progetto

  2. Il codice evolve, le dipendenze cambiano

  3. Il diagramma diventa una bugia decorativa

  4. Nessuno lo aggiorna perché è penoso

  5. I nuovi arrivati si basano su quello e commettono errori

probleme diagrammes obsoletes

La questione non è serve avere dei diagrammi ? — tutti sanno di sì. La questione è :chi li mantiene aggiornati?

La risposta: nessuno. A meno che non sia automatico.

La soluzione: un pipeline deterministico Knowledge Graph → PlantUML

Il principio è semplice: al posto di disegnare i diagrammi a mano, ligenera dalla struttura reale del codice.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

actor Développeur
component "Graphify
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

actor Développeur
component "Graphify
(pip install graphifyy)" as Graphify
collections "graphify-out/graph.json
(Grafo della conoscenza)" as KGJSON
component "Plugin Gradle per PlantUML
(generateKnowledgeGraphDiagram)" as Plugin
component "KnowledgeGraphParser" as Parser
component "KnowledgeGraphRenderer" as Renderer
component "PlantumlService
(validazione + rendering PNG)" as PS
collections "diagrammi/knowledge-graph/\n(.puml + .png)" as Output

Développeur --> Graphify : graphify . --no-viz
Graphify --> KGJSON : extrait la structure\ndu code source
Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram
Plugin --> Parser : parse(graph.json)
Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés)
Plugin --> Renderer : render(graph, filters)
Renderer --> Plugin : code PlantUML\ndéterministe
Plugin --> PS : validateSyntax + generateImage
PS --> Output : .puml + .png

note bottom of Plugin
  Pipeline DÉTERMINISTE
  Aucun appel LLM
  Résultat reproductible
end note

@enduml

Due comandi. È tutto.

# Étape 1 : extraire le Knowledge Graph
graphify . --no-viz

# Étape 2 : générer les diagrammes PlantUML
./gradlew generateKnowledgeGraphDiagram

Il risultato? Dei file`.puml` et .png`in`diagrams/knowledge-graph/, versionati in Git, sempre aggiornati rispetto al codice.

Passo 1: Installare Graphify e estrarre il Knowledge Graph

Installazione

JBake CLI Commands ` # Initialize a new JBake project jbake -i

Bake (generate) the site jbake -b

Bake and serve locally jbake -b -s

Bake and watch for changes jbake -b --reset

Specify source and destination jbake source_folder output_folder

Clear the output directory before baking jbake -b . output --reset ` Graphify è uno strumento Python che analizza il tuo codebase e costruisce un grafo di conoscenze strutturato:

# Méthode recommandée
uv tool install graphifyy && graphify install --platform opencode

# Alternative avec pip
pip install graphifyy && graphify install --platform opencode

Configurare le esclusioni

Creare un file`.graphifyignore`alla radice del progetto per escludere i file che non fanno parte della logica di business :

# Secrets — JAMAIS dans le graphe
*-context.yml
*.env

# Fichiers générés
build/
.gradle/

# Tests fonctionnels
src/functionalTest/

Estrarre il Knowledge Graph

graphify . --no-viz

La bandiera`--no-viz`Salta la generazione HTML (inutile in una pipeline Gradle). Il risultato è un file`graphify-out/graph.json`contenente :

  • nodi: classi, funzioni, file — con il loro tipo e comunità

  • Lischerelazioni tra nodi (EXTRACTED dal codice, INFERRED dal LLM)

  • Comunità: raggruppamenti automatici di nodi collegati

Exemple de structure graph.json
{
  "nodes": [
    {"id": "0", "label": "LlmService", "file_type": "code", "community": 0},
    {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0},
    {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1}
  ],
  "links": [
    {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9},
    {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7}
  ]
}

Il codice sorgente (.kt, .java) viene analizzato localmente da tree-sitter,senza appello LLM. Solo i file di documentazione (.adoc, .md) richiedono una chiamata LLM per l’estrazione semantica. Quindi`--update`sul codice Kotlin è quasi istantaneo.

Passo 2: Il plugin Gradle trasforma il Knowledge Graph in PlantUML

Architettura della pipeline

Il plugin`com.cheroliv.plantuml`integra un compito`generateKnowledgeGraphDiagram`che trasforma`graph.json`in diagrammi PlantUML in modototalmente deterministico:

architecture pipeline kg

I componenti interni

Componente Ruolo

KnowledgeGraphParser

Parse`graph.json`— supporta 3 formati : graphify nativo (nodes(No output)links), legacy (communities), flat. Risolve gli ID numerici in etichette.

KnowledgeGraphRenderer

Trasforma deterministicamente un`KnowledgeGraph`in codice PlantUML. Gruppi per tipo, comunità in package, legenda automatica.

GenerateKnowledgeGraphDiagramTask

Task Gradle che orchestra : parse → render → validate → PNG. Configurabile tramite proprietà Gradle.

kgmodels.kt

Modelli di dati:`KnowledgeGraph`, KnowledgeGraphNode, KnowledgeGraphEdge, KnowledgeGraphCommunity, EdgeType.

PlantumlService

Validazione sintattica + rendering PNG (riutilizzato da tutte le attività del plugin).

Regole di rendering

Il renderer applica convenzioni visive deterministiche :

Tipo di spigolo Notazione PlantUML Significato

ESTRATTI

-→(tratto pieno, nero)

Relazione estratta dal codice sorgente (certezza)

DEDOTTO

..>(linea punteggiata)

Relazione inferita dall’LLM (punteggio di fiducia)

AMBIGUO

--x(tratto rosso punteggiato)

Relazione ambigua (da verificare)

Le comunità vengono renderizzate come pacchetti PlantUML con una palette di colori automatica.

Fase 3: Utilizzo quotidiano

Diagramma completo

# Générer le diagramme du Knowledge Graph complet
./gradlew generateKnowledgeGraphDiagram

Uscita :`diagrams/knowledge-graph/knowledge-graph-full.puml`+.png

Filtra per comunità

# Une seule communauté
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.community=community_0

# Limiter le nombre de noeuds (lisibilité)
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.community=community_0 \
  -Pplantuml.kg.maxNodes=15

Filtra per tipo di bordo

# Uniquement les relations certaines (EXTRACTED)
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.edgeTypes=EXTRACTED

# Relations certaines + inférées
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED

Filtra per tipo di nodo e confidenza

# Uniquement les classes de code
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.nodeTypes=code

# Seuil de confiance minimum (pour les INFERRED)
./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.minConfidence=0.7

Directory di output personalizzata

./gradlew generateKnowledgeGraphDiagram \
  -Pplantuml.kg.outputDir=docs/architecture

Riferimento completo delle proprietà

Proprietà difetto Description

plantuml.kg.community

(tutte)

Filtrare le comunità per nome (corrispondenza di sottostringa)

plantuml.kg.edgeTypes

(tutti)

Tipi di archi separati da virgole:`EXTRACTED`, INFERRED, AMBIGUOUS

plantuml.kg.minConfidence

0.0

Soglia minima di confidenza per gli archi

plantuml.kg.maxNodes

(illimitato)

Numero massimo di nodi da visualizzare

plantuml.kg.nodeTypes

tutti

Tipi di nodi separati da virgole (es.class, code)

plantuml.kg.outputDir

diagrams/knowledge-graph

Directory di output per i file`.puml` et .png

Il pipeline completo in un workflow Gradle

Workflow type

workflow complet

Integrazione nel ciclo di sviluppo

Il pipeline si integra naturalmente nelle fasi chiave dello sviluppo :

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ]

@startuml
skinparam backgroundColor #FEFEFE

state "Sviluppo" as dev
state "Estrazione
^^^^^
 Syntax Error? (Assumed diagram type: state)

@startuml
skinparam backgroundColor #FEFEFE

state "Sviluppo" as dev
state "Estrazione
graficare . --no-viz" as extract
state "Generazione
./gradlew generateKnowledgeGraphDiagram" as generate
state "Commit\ndiagrammi versionati" as commit

[*] --> dev
dev --> extract : Code modifié
extract --> generate : graph.json à jour
generate --> commit : .puml + .png générés
commit --> dev : Diagrammes dans le repo

note right of extract
  Quasi instantané sur du code Kotlin
  (tree-sitter, pas de LLM)
end note

note right of generate
  Déterministe
  Pas de LLM
  Résultat reproductible
end note

@enduml

Aggiornamento incrementale

Quando il codice cambia, non ricostruiamo tutto il grafo da zero :

# Mise à jour incrémentale (fichiers modifiés uniquement)
graphify . --update

# Puis régénérer les diagrammes
./gradlew generateKnowledgeGraphDiagram

--update`re-estrae solo i file modificati (rilevati tramite SHA256 in`graphify-out/cache/). Sul codice Kotlin, è quasi istantaneo perché tree-sitter funziona localmente senza chiamate LLM.

Il dogfooding: il plugin si documenta da sé

Il plugin PlantUML esiste per trasformare i prompt in diagrammi. Può anche trasformare il Knowledge Graph del suo proprio codebase in diagrammi di documentazione. È dogfooding : il plugin consuma il proprio servizio.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "Pipeline normale
(utente → diagrammi)" as normal {
^^^^^
 Syntax Error? (Assumed diagram type: activity)

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "Pipeline normale
(utente → diagrammi)" as normal {
    [Fichier .prompt] as prompt
    [LlmService\n+ ApiKeyPool] as llm1
    [ProcessPlantumlPromptsTask] as task1
    [Diagramme PNG] as out1

    prompt --> task1
    task1 --> llm1
    llm1 --> out1
}

package "Pipeline Knowledge Graph
(deterministico, senza LLM)" as kg {
    [graphify-out/graph.json] as kgjson
    [KnowledgeGraphParser] as parser
    [KnowledgeGraphRenderer] as renderer
    [PlantumlService] as ps
    [Diagramme PNG\n(documentation du plugin)] as out2

    kgjson --> parser
    parser --> renderer
    renderer --> ps
    ps --> out2
}

package "Pipeline Dogfooding
(LLM → documentazione del plugin)" as dogfood {
    [GraphifyPromptAdapter] as gpa
    [Fichiers .prompt\nauto-générés] as auto_prompt
    [LlmService\n+ ApiKeyPool] as llm2
    [ProcessPlantumlPromptsTask] as task2
    [Diagramme PNG\n(documentation LLM)] as out3

    kgjson --> gpa
    gpa --> auto_prompt
    auto_prompt --> task2
    task2 --> llm2
    llm2 --> out3
}

note "Stesso LlmService, stesso ApiKeyPool,
stesso PlantumlService
— ZERO duplicazione" as N

@enduml

Compiti Gradle associati :

Compito LLM ? Description

generateKnowledgeGraphDiagram

No

Trasforma`graph.json`in PlantUML (deterministico)

generateDiagramDocs

Sì

Genera dei`.prompt`dal grafo, li tratta tramite LLM (dogfooding)

# Documentation déterministe (rapide, pas de LLM)
./gradlew generateKnowledgeGraphDiagram

# Documentation LLM (plus riche, consomme des tokens)
./gradlew generateDiagramDocs

Perché è deterministico (e perché conta)

Il punto chiave del pipeline`generateKnowledgeGraphDiagram`(No output)non chiama alcun LLM. La trasformazione`graph.json` → PlantUML est une fonction pure.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

rectangle "Pipeline deterministico
(generateKnowledgeGraphDiagram)" as det {
^^^^^
 Syntax Error? (Assumed diagram type: activity)

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

rectangle "Pipeline deterministico
(generateKnowledgeGraphDiagram)" as det {
    [graph.json] as json
    [KnowledgeGraphParser] as parser
    [KnowledgeGraphRenderer] as renderer
    [PlantUML code] as puml

    json --> parser : parse
    parser --> renderer : KnowledgeGraph
    renderer --> puml : render (fonction pure)
}

rectangle "Pipeline LLM
(processPlantumlPrompts)" as llm {
    [.prompt] as prompt
    [LlmService] as llmSvc
    [ChatModel] as model
    [PlantUML code] as puml2

    prompt --> llmSvc
    llmSvc --> model : API call
    model --> puml2 : réponse non-déterministe
}

note bottom of det
  Même entrée → même sortie
  Pas de latence réseau
  Pas de coût en tokens
  Reproductible en CI
end note

note bottom of llm
  Même entrée → sortie variable
  Latence réseau (1-5s)
  Coût en tokens
  Nécessite une clave API
end note

@enduml

I vantaggi concreti:

vantaggio Impatto

riproducibilità

Anche`graph.json`→ lo stesso diagramma. Esattamente. Ogni volta.

zero costo

Nessuna chiamata LLM = nessun token = nessuna fattura API

Zero latenza

Parse + render impiega ~100ms, non 1-5 secondi.

Compatibile CI

Nessuna chiave API necessaria. Nessun test flaky dovuto a una risposta LLM variabile.

Versionabile

Le .puml`Il testo generato è del testo. Si può`diff, il reviewer nella PR, versionarlo in Git.

Diagrammi del pipeline stesso

Per chiudere il cerchio, ecco il diagramma della pipeline così com’è generato dal plugin :

pipeline sequence

Integrazione nella governance del progetto

Nel nostro progetto, questo pipeline si integra in una strategia di gestione del contesto EAGER/LAZY per l’agente IA. Il Knowledge Graph sostituisce la documentazione architetturale manuale con un grafo strutturato, interrogabile e auto-aggiornato.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 16) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "EAGER\n(sempre carico)" as eager {
    [PROMPT_REPRISE.adoc\n(contexte session)] as pr
    [INDEX.adoc\n(vue d'ensemble)] as idx
    [GRAPH_REPORT.adoc\n(~50 lignes)] as gr
}

package "LAZY — Strategia\n(su richiesta)" as lazy_strat {
    [Méthodologies] as meth
    [Archives sessions] as sessions
}

package "LAZY — Graphify
^^^^^
 Syntax Error? (Assumed diagram type: component)

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "EAGER\n(sempre carico)" as eager {
    [PROMPT_REPRISE.adoc\n(contexte session)] as pr
    [INDEX.adoc\n(vue d'ensemble)] as idx
    [GRAPH_REPORT.adoc\n(~50 lignes)] as gr
}

package "LAZY — Strategia\n(su richiesta)" as lazy_strat {
    [Méthodologies] as meth
    [Archives sessions] as sessions
}

package "LAZY — Graphify
(query mirate)" as lazy_graph {
    [graph.json] as gj
    [Queries\n(query/path/explain)] as queries
}

package "Pipeline PlantUML\n(auto-generato)" as puml {
    [generateKnowledgeGraphDiagram] as kgTask
    [generateDiagramDocs] as ddTask
    [Diagrammes PNG] as diagrams
}

Agent --> eager : Lit en début de session
Agent ..> lazy_strat : Charge si type détecté
Agent ..> lazy_graph : Query si besoin structurel
kgTask --> diagrams : Déterministe
ddTask --> diagrams : Via LLM

note right of gr
  Condensé du Knowledge Graph
  God nodes + communautés
  Remplace ECOSYSTEM_OVERVIEW
  (225 lignes → 50 lignes)
end note

@enduml

Il matrimonio dei due sistemi è complementare :

  • La strategia gestisce il QUAND e il COMMENT— governance, workflow, archiviazione

  • Graphify gestisce il QUOI e il OÙ — structure du code, relations, requêtes ciblées

_ La strategia di sessione gestisce ilQUANDO et le COME(governance, workflow, soglie), Graphify gestisce ilCosa et le dove(struttura del codice, relazioni, query mirate). Il pipeline PlantUML gestisce ilcon cosa(diagrammi deterministici, versionati, sempre aggiornati) _

Impostazione: lista di controllo in 5 minuti

# Fase Ordine

1

Installa Graphify

uv tool install graphifyy

2

Configurare le esclusioni

creare`.graphifyignore`

3

Estrarre il Knowledge Graph

graphify . --no-viz

4

Generare i diagrammi

./gradlew generateKnowledgeGraphDiagram

5

Effettuare il commit dei risultati

git add diagrams/knowledge-graph/

# Script complet en 5 commandes
uv tool install graphifyy
cat > .graphifyignore << 'EOF'
*-context.yml
*.env
build/
.gradle/
EOF
graphify . --no-viz
./gradlew generateKnowledgeGraphDiagram
git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/

Trappole e mitigazioni

trappola Description Mitigazione

Grafo troppo denso

Un grande progetto genera centinaia di nodi illeggibili

usare`-Pplantuml.kg.maxNodes=30`e filtra per comunità

Esclusioni troppo ampie

Troppi file in`.graphifyignore`riduce il valore del grafo

# Gradle Integration JBake can be integrated into Gradle builds using the JBake Gradle plugin or by calling the JBake CLI directly:

Direzione delle frecce

Le arete INFERRED possono avere una direzione ambigua

Filtra per`-Pplantuml.kg.edgeTypes=EXTRACTED`solo per le relazioni certe

Grafo obsoleto

Il codice cambia ma il grafo non viene ricostruito

utilizzare`graphify . --update`regolarmente o il hook git`graphify hook install`

Costo aggiornato

Gli aggiornamenti incrementali sono quasi gratuiti (tree-sitter local)

Solo i documenti (.adoc) consumano token LLM

Ciò che si ottiene alla fine

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ]

@startuml
skinparam backgroundColor #FEFEFE

rectangle "prima" as avant {
    card "Diagrammi disegnati a mano
Sempre obsoleti
^^^^^
 Syntax Error? (Assumed diagram type: activity)

@startuml
skinparam backgroundColor #FEFEFE

rectangle "prima" as avant {
    card "Diagrammi disegnati a mano
Sempre obsoleti
Nessuno li aggiorna" as av1 #FDEDEC
}

rectangle "DOPO" as apres {
    card "Diagrammi generati automaticamente
Sempre aggiornati con il codice
Versionati in Git
Deterministici e riproducibili" as ap1 #E8F8E8
}

avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram

@enduml

I benefici concreti:

Profitto Dettaglio

Documentazione sempre aggiornata

I diagrammi riflettono il codice corrente, non uno snapshot manuale

Zero sforzo di manutenzione

I diagrammi vengono rigenerati ad ogni build

Riduzione del debito tecnico

Non è più necessario mantenere i diagrammi a mano

Contesto visivo per i nuovi

Un nuovo sviluppatore comprende l’architettura guardando i diagrammi

fine-tuning potenziale

Le coppie (sottografo → diagramma) sono esempi di addestramento IA

Validazione automatica

`PlantumlService.validateSyntax()`verifica ogni diagramma generato

Onboarding rapido

5 diagrammi = visione completa dell’architettura

_ Chi ha un _perché può sopportare ogni come. __

Il perché: diagrammi sempre aggiornati. Il come: due comandi in una pipeline Gradle.

Articoli correlati