Integrirajte Graphify u Gradle workflow : od Knowledge graph-a do PlantUML dijagrama u jednoj naredbi
Објављено 19 April 2026
- Problem: dijagrami uvijek zaostaju u odnosu na kod
- Решение: детерминистични конвејер Knowledge Graph → PlantUML
- Корак 1 : Инсталирај Graphify и извлекни Knowledge Graph
- Корак 2: Gradle плагин трансформише Knowledge Graph у PlantUML
- Корак 3 : Дневна употреба
- Kompletan pipeline u Gradle workflow-u
- Dogfooding: plugin se dokumentuje sam
- Zašto je deterministički (i zašto to važi)
- Dijagrami samog pipeline-a
- Интеграција у управљању пројектом
- Priprema: check‑list u 5 minuta
- Zalazi i mitigacije
- Šta se na kraju dobija
- Linkovi
Vaša codebase raste. Zavisnosti između modula se množe. Arhitektonska dokumentacija postaje zastarela pre nego što bude napisana. Ako bi vaš Gradle build mogao automatski da generiše ażurne dijagrame iz stvarne strukture koda? To je tačno ono što radi pipeline Graphify + PlantUML Gradle Plugin :`graphify . --no-viz`izvuče Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`pretvara ga u PlantUML dijagrame. Nula LLM, nula priručnik, 100% deterministički.
Problem: dijagrami uvijek zaostaju u odnosu na kod
Svaki projekat koji prelazi nekoliko hiljada linija poznaje ovaj sindrom :
-
На цртамо архитектурни дијаграм на почетку пројекта
-
Код се мења, зависности се мењају
-
Dijagram postaje dekorativna laž
-
Niko ne ažurira to jer je mučno.
-
Novi dolazci se oslanjaju na to i prave greške
@startuml
skinparam backgroundColor #FEFEFE
skinparam ActivityBackgroundColor #FDEDEC
skinparam ActivityDiamondBackgroundColor #FFF3CD
start
:Dijagram arhitekture kreiran\n(ručno, rukoma);
:Kod se razvija\n(nove klase, nove zavisnosti);
:Neaktuelan dijagram\n(ne odražava više kod);
if (Qui met à jour ?) then (Personne)
:Ложна документација;
note right: Novi programeri\n se bazuju na njemu... i prave greške
else (Quelqu'un)
:Ručno ažuriranje\n(2-3 sata rada);
note right: Већ застарјело\nна следећа PR
endif
stop
@enduml
Pitanje nije da li su potrebni dijagrami? — svi znaju da je da. Pitanje je:Ko ih održava ažurno?
Odgovor: nitko. Osim ako je automatsko.
Решение: детерминистични конвејер Knowledge Graph → PlantUML
Princip je jednostavan: umesto da crtamo dijagrame ručno, mi ihгенерише из реалне структуре кода.
@startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify\n(pip install graphifyy)" as Graphify collections "graphify-out/graph.json\n(Znanje Graf)" as KGJSON component "PlantUML Gradle Plugin\n(generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "KnowledgeGraphRenderer" as Renderer component "PlantumlService\n(validacija + renderovanje PNG)" as PS collections "dijagrami/knowledge-graph/\n(.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : извлачи структуру\nизворног кода Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(čvorovi + grane + zajednice) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : kod PlantUML\ndeterministicki Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Cevovod DÉTERMINISTE Nijedan poziv LLM Rezultat reproducibilan end note @enduml
Dve komande. To je sve.
# Étape 1 : extraire le Knowledge Graph
graphify . --no-viz
# Étape 2 : générer les diagrammes PlantUML
./gradlew generateKnowledgeGraphDiagram
Rezultat? Datoteke`.puml` et .png`u`diagrams/knowledge-graph/, verzionisani u Gitu, uvek ażurni sa kodom.
Корак 1 : Инсталирај Graphify и извлекни Knowledge Graph
Инсталација
Graphify je alat u Pythonu koji analizira vašu bazu koda i gradi strukturovan graf znanja :
# Méthode recommandée
uv tool install graphifyy && graphify install --platform opencode
# Alternative avec pip
pip install graphifyy && graphify install --platform opencode
Настројите искљуке
Креирај фајл`.graphifyignore`у корени пројекта да би се искључили фајлови који нису дел пословне логике :
# Secrets — JAMAIS dans le graphe
*-context.yml
*.env
# Fichiers générés
build/
.gradle/
# Tests fonctionnels
src/functionalTest/
Извуци граф знања
graphify . --no-viz
Zastava`--no-viz`Preskače generisanje HTML (nije potrebno u Gradle pipeline). Rezultat je datoteka`graphify-out/graph.json`sadrži :
-
Čvorovi: klase, funkcije, fajlovi — sa njihovim tipom i zajednicom
-
ivice: odnosi između čvorova (EXTRACTED iz koda, INFERRED od LLM)
-
Заједнице: automatska grupisanja povezanih čvorova
Пример структуре`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}
]
}
|
Izvorni kod ( |
Корак 2: Gradle плагин трансформише Knowledge Graph у PlantUML
Архитектура конвејера
Додатак`com.cheroliv.plantuml`uključuje zadatak`generateKnowledgeGraphDiagram`koji transforma`graph.json`u dijagramima PlantUML na načinpotpuno deterministički:
@startuml
skinparam backgroundColor #FEFEFE
participant "Gradle" as G
participant "GenerateKnowledgeGraphDiagramTask" as Task
participant "KnowledgeGraphParser" as Parser
participant "KnowledgeGraphRenderer" as Renderer
participant "PlantumlService" as PS
collections "graphify-out/graph.json" as JSON
G -> Task : izvrši
Task -> JSON : читати
Task -> Parser : parse(graph.json)
Parser --> Task : KnowledgeGraph\n(čvorovi + grane + zajednice)
Task -> Renderer : render(graph, filters)
Renderer --> Task : PlantUML\n(детерминист)
Task -> PS : validateSyntax(plantumlCode)
alt syntaxe valide
Task -> PS : generateImage → .png
else syntaxe invalide
Task -> Task : Sacuvaj .puml sa upozorenjem
end
@enduml
Unutrašnji komponenti
| komponent | Uloga |
|---|---|
|
Parse |
|
Transformiši deterministički`KnowledgeGraph`у коду PlantUML. Групова по тип, заједнице у пакетима, аутоматска легенда. |
|
Gradle zadatak koji orkestruje: parse → render → validate → PNG. Konfigurisan preko Gradle svojstava. |
|
Modeli podataka :`KnowledgeGraph`, |
|
Sintaksna validacija + PNG renderovanje (ponovo korišćen svim zadacima plugina) |
Pravila renderovanja
Renderer primenjuje deterministicke vizuelne konvencije :
| Tip ivice | Notacija PlantUML | значење |
|---|---|---|
EXTRACTED |
|
Izveznuta relacija iz izvorni koda (sigurnost) |
zaključeno |
|
Relacija zaključena od LLM (ocena poverenja) |
ДВОСМИСЛЕН |
|
Nejednoznačna veza (da se proveri) |
Komunitarne zajednice su prikazane kao PlantUML paketi sa automatskom paletom boja.
Корак 3 : Дневна употреба
Potpuni dijagram
# Générer le diagramme du Knowledge Graph complet
./gradlew generateKnowledgeGraphDiagram
Излаз:`diagrams/knowledge-graph/knowledge-graph-full.puml`+.png
Филтрирај по заједници
# 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
Filtriraj po tipu grane
# Uniquement les relations certaines (EXTRACTED)
./gradlew generateKnowledgeGraphDiagram \
-Pplantuml.kg.edgeTypes=EXTRACTED
# Relations certaines + inférées
./gradlew generateKnowledgeGraphDiagram \
-Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED
Filtriraj po tipu čvora i poverenju
# 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
Прилагођени излазни директоријум
./gradlew generateKnowledgeGraphDiagram \
-Pplantuml.kg.outputDir=docs/architecture
Пуна референца својстава
| svojina | подразумевано | Опис |
|---|---|---|
|
(sve) |
Филтрирај заједнице по називу (подударење подниза) |
|
(sve) |
Tipovi grana odvojeni zarezom :`EXTRACTED`, |
|
|
Minimalni prag poverenja za ivice |
|
(неограничено) |
Maksimalni broj čvorova za prikaz |
|
(svi) |
Tipovi čvorova razdvojeni zarezami (prim. |
|
|
Izlazni direktorijum za fajlove`.puml` et |
Kompletan pipeline u Gradle workflow-u
Tip radnog toka
@startuml
skinparam backgroundColor #FEFEFE
skinparam ActivityBackgroundColor #E8F4FD
skinparam ActivityDiamondBackgroundColor #FFF3CD
skinparam ActivityBorderColor #2C3E50
start
partition "EXTRACTION" {
:графиковати . --no-viz;
note right: Analiziraj izvorni kod\ntree-sitter (lokalno, bez LLM)
:graphify-out/graph.json;
note right: Čvorovi + ivice\n+ zajednice
}
partition "GÉNÉRATION" {
:./gradlew generateKnowledgeGraphDiagram;
note right: Pipeline deterministički\nparsirati → render → validate → PNG
if (Filtres actifs ?) then (Oui)
:Примени филтри\n(community, edgeTypes,\nmaxNodes, nodeTypes);
else (Non)
:Potapun dijagram;
endif
:diagrams/knowledge-graph/\nknowledge-graph-full.puml\nknowledge-graph-full.png;
}
partition "INTÉGRATION" {
:git add diagrams/knowledge-graph/;
:git commit;
note right: Diagrammes versionnés\ntoujours à jour avec le code
}
stop
@enduml
Integracija u razvojni ciklus
Pipeline se prirodno uklapa u ključnim fazama razvoja:
@startuml skinparam backgroundColor #FEFEFE state "Развој" as dev state "Извлаčenje\ngraphify . --no-viz" as extract state "Генерација\n./gradlew generateKnowledgeGraphDiagram" as generate state "Commit\nдијаграми верзионисани" as commit [*] --> dev dev --> extract : Izmenjeni kod extract --> generate : graph.json ажуриран generate --> commit : .puml + .png generisani commit --> dev : дијаграми у репу note right of extract Квази instantaneous на коду Kotlin (tree-sitter, без LLM) end note note right of generate deterministicki Nema LLM Ponovljiv rezultat end note @enduml
Inkrementalno ažuriranje
Kada se kod promeni, ne se ponovo gradi sav graf od nule:
# Mise à jour incrémentale (fichiers modifiés uniquement)
graphify . --update
# Puis régénérer les diagrammes
./gradlew generateKnowledgeGraphDiagram
|
|
Dogfooding: plugin se dokumentuje sam
PlantUML plugin postoji da pretvara upite u dijagrame. Takode može pretvoriti Knowledge Graph svoje vlasno codebase u dokumentacione dijagrame. To je dogfooding : plugin konzumira sopstvenu uslugu.
@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
package "Normalni pajplajn\n(korisnik → dijagrami)" 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 "Knowledge Graph pajplajn\n(deterministički, bez LLM-a)" 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 "Dogfooding pajplajn\n(LLM → dokumentacija dodatka)" 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 "Isti LlmService, isti ApiKeyPool,\nisti PlantumlService\n— NULA duplikacije" as N
@enduml
Povezani Gradle zadaci:
| zadatak | LLM ? | опис |
|---|---|---|
|
Ne |
Преобрази`graph.json`у PlantUML (детерминистично) |
|
Da |
Генерира неке`.prompt`од графa, обрађује их преко LLM (dogfooding) |
# Documentation déterministe (rapide, pas de LLM)
./gradlew generateKnowledgeGraphDiagram
# Documentation LLM (plus riche, consomme des tokens)
./gradlew generateDiagramDocs
Zašto je deterministički (i zašto to važi)
Кључна тачка пајплайна`generateKnowledgeGraphDiagram` : On ne poziva nikog LLM. transformacija`graph.json`→ PlantUML je čista funkcija.
@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
rectangle "DETERMIOSTIČKI pipeline\n(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 "LLM pipeline\n(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
Isti ulaz → isti izlaz
Bez mrežnog kašnjenja
Bez troška tokena
Reproduktivno u CI-u
end note
note bottom of llm
Isti ulaz → varijabilan izlaz
Mrežna latencija (1-5s)
Trošak tokena
Zahteva API ključ
end note
@enduml
Конкретне предности:
| Предност | утицај |
|---|---|
Репродуктивност |
исте`graph.json`→ истог дијаграма. Тачно. Увек. |
Нула трошак |
Nema poziva LLM = nema tokena = nema računa API. |
Nula latencije |
Parsiranje + renderovanje traje ~100ms, ne 1-5 sekundi. |
savладан sa CI |
Nije potreban API ključ. Nema nestabilnog testa zbog varijabilnog LLM odgovora. |
верzionabilan |
Le |
Dijagrami samog pipeline-a
Da bismo zaključili petlju, ovo je dijagram pipeline-a kao što bi ga generisao plugin:
@startuml
skinparam backgroundColor #FEFEFE
participant "Развојник" as Dev
participant "Gradle" as G
participant "GenerateKnowledgeGraphDiagramTask" as Task
participant "KnowledgeGraphParser" as Parser
participant "KnowledgeGraphRenderer" as Renderer
participant "PlantumlService" as PS
collections "graphify-out/graph.json" as JSON
collections "diagrams/knowledge-graph/" as Out
Dev -> G : ./gradlew generateKnowledgeGraphDiagram
G -> Task : izvršiti
Task -> JSON : читати
Task -> Parser : parse(graph.json)
Parser --> Task : KnowledgeGraph
alt filtres actifs
Task -> Task : primeniti filtre\n(community, edgeTypes, maxNodes…)
end
Task -> Renderer : render(graph, filters)
Renderer --> Task : kod PlantUML
Task -> PS : validateSyntax()
alt valide
Task -> PS : generateImage()
PS --> Out : .puml + .png
else invalide
Task -> Out : .puml (са упозорењем)
end
@enduml
Интеграција у управљању пројектом
U našem projektu, ovaj pipeline se uključi u strategiju upravljanja kontekstem EAGER/LAZY za agenta AI. Knowledge Graph zamenuje ručnu dokumentaciju arhitekture strukturiranim, upitnim i samoodažurivim grafom.
@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
package "EAGER\n(uvijek uczitan)" 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 — Strategija\n(na zahtev)" as lazy_strat {
[Méthodologies] as meth
[Archives sessions] as sessions
}
package "LAZY — Graphify\n(ciljani upiti)" as lazy_graph {
[graph.json] as gj
[Queries\n(query/path/explain)] as queries
}
package "Pipeline PlantUML\n(automatski generiran)" as puml {
[generateKnowledgeGraphDiagram] as kgTask
[generateDiagramDocs] as ddTask
[Diagrammes PNG] as diagrams
}
Agent --> eager : Pročitan na početku sesije
Agent ..> lazy_strat : Učitaj ako je tip detektovan
Agent ..> lazy_graph : ako je estrutualna potreba
kgTask --> diagrams : детерминистички
ddTask --> diagrams : Preko LLM
note right of gr
Kondenzovan graf znanja
Čvorovi Boga + zajednice
Zameni ECOSYSTEM_OVERVIEW
(225 linija → 50 linija)
end note
@enduml
Bračenje dva sistema je komplementarno:
-
Strategija upravlja KAD i KAKO— upravljanje, radni tok, arhiviranje
-
Graphify rukuje šta i gde— struktura koda, relacije, ciljani upiti
_ Стратегија сесије управљаКАД et le kako(upravljanje, tok rada, pragovi), Graphify upravljašta et le Gde(структура кода, односе, цељни упити). PlantUML pipeline управљаСА ШТА?(deterministički dijagrami, verzionirani, uvek ažurirani). _
Priprema: check‑list u 5 minuta
| # | Корак | narudžba |
|---|---|---|
1 |
Instaliraj Graphify |
|
2 |
Konfigurisati isključivanja |
креирати`.graphifyignore` |
3 |
Izvući Knowledge Graph |
|
4 |
Generiši dijagrame |
|
5 |
Комитовати резултате |
|
# 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/
Zalazi i mitigacije
| Капчао | Opis | Mitigacija |
|---|---|---|
Preterano gust graf |
Велики пројекат генерише стотине нечитавих чворова |
koristiti`-Pplantuml.kg.maxNodes=30`и филтрирај по заједници |
Previše širi iskljuci |
Previše fajlova u`.graphifyignore`smanjuje vrednost grafa |
Počinuti isključivanjem samo credentials i build |
Smer strelica |
INFERRED ivice mogu imati nejednoznačan pravac |
Филтрирај по`-Pplantuml.kg.edgeTypes=EXTRACTED`samo za određene odnose |
Zastareli graf |
Код се мења, али граф није опет построен |
користити`graphify . --update`redovito ili git hook`graphify hook install` |
Ažurirana cena |
Inkrementalna ažuriranja su skoro besplatna (tree-sitter lokalno) |
Samo docs( |
Šta se na kraju dobija
@startuml
skinparam backgroundColor #FEFEFE
rectangle "PRED" as avant {
card "Ručno nacrtani dijagrami\nUvek zastareli\nNiko ih ne ažurira" as av1 #FDEDEC
}
rectangle "POSLE" as apres {
card "Automatski generisani dijagrami\nUvek usklađeni sa kodom\nverzionisani u Git-u\nDeterministički i reproduktivni" as ap1 #E8F8E8
}
avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram
@enduml
Конкретне користи:
| Прибут | detalj |
|---|---|
Документација увек ажурирана |
Dijagrami odražavaju trenutni kod, a ne ručni snapshot |
Nula napora održavanja |
Dijagrami se regenerišu na svakom build-u |
Smanjenje tehničkog duga |
Више не морате да одржавате дијаграме ручно. |
Визуелни контекст за нових |
Novi programer razume arhitekturu gledajući dijagrame. |
potenijalno podešavanje |
Parovi (podgraf → dijagram) su primeri obuke veštačke inteligencije |
Автоматска валидација |
`PlantumlService.validateSyntax()`proverava svaki generisani dijagram |
Brzo uvođenje |
5 dijagrama = kompletan pogled na arhitekturu |
_ Tko ima _zašto može da nosi sve kako. __
Za zašto: dijagrami koji su uvek ažurni. Za kako: dve komande u Gradle pipeline-u.
Linkovi
-
Супер савети за команду fg— претексни чланак о терминаљском току рада
Повезани чланци
18 May 2026