Az architektúradiagramodnak nincs értelme

Ha egy fejlesztő elé teszünk egy építési tervrajzot, jó eséllyel egy kukkot sem fog érteni belőle. Ez alapvetően rendben is van, hiszen a jelölések, rövidítések és feliratok nem neki szólnak. A kivitelező - akinek az adott tervrajz szól - viszont első ránézésre tudja, milyen téglából épül a fal, hol lesz a fürdőszoba és merre fut a vizes bekötés. Az építőipar évtizedek alatt kialakította a maga konvencióit.

A szoftverfejlesztésben is készülnek tervek, ugyanígy szakmabeliek rajzolják őket szakmabelieknek. Egységes jelölésrendszert mégis ritkán használunk, így a másik fél sokszor úgy áll az ábra előtt, mint mi az iménti tervrajz előtt. Még rosszabb, amikor egy részét érti, a többit pedig odaképzeli. Ezek a feltételezések gyakran több kárt okoznak, mint ha egyszerűen megkeresné a készítőt, és tisztáznák a sötét foltokat.

Miért lesz mindenből egy nagy ábra?

Egy épületet a terv szerint felépítenek, utána pedig ritkán toldják meg pár emelettel, vagy raknak a tetejére szélerőművet. Egy szoftver ezzel szemben a változtathatóságból él, a soft szó sem véletlenül került bele a nevébe. Csakhogy ami folyamatosan változik, arról a rajzok előbb-utóbb elavulnak.

Ez minden dokumentációra igaz, és sokaknak bizony meg is keseríti a munkáját, hiszen a dokumentációt naprakészen kell tartani. Az ábráknál ez különösen fájdalmas. A diagramkészítő eszközök fejlettek, a cégek igen komoly összegeket fizetnek értük, de a diagramok frissítése mégis kézimunka. Bekerül egy új komponens, és vele együtt az összes odavezető nyilat át kell rajzolni, pedig az ábra addig szépen el volt rendezve. Utána meg úgy néz ki, mint egy Word-dokumentum, amibe gyanútlanul beillesztettek egy képet.

Ráadásul habár az IDE billentyűparancsait fejből tudjuk, a Lucidchart vagy az Excalidraw nyílrajzolását már kevésbé. Emiatt egy apró módosítás is órákat vihet el, ahogy bénázunk az eszközzel.

Ami pedig ennyi munkával jár, azt igyekszünk minimalizálni, a legkézenfekvőbb módon: kevesebb ábrát rajzolunk. Így születik meg az az egyetlen nagy diagram, amit a CTO-nak is megmutatunk, az új fejlesztő onboardingján is előveszünk, a security auditra is elküldünk, és amit az infra csapat körbedobozol a subnetekkel. Látszólag sok munkát spórolunk vele, de haszna már kevesebb van. A kódból generált diagramok sem oldják meg magától ezt a helyzetet: tíz ábra tíz forrásfájlt jelent, amit karban kell tartani, és így ez is az egy nagy közös ábra felé csábít.

És akkor csodálkozunk, hogy senki sem érti

Néhány hiba újra és újra előjön. Egyik sem különösebben bonyolult, mégis elég ahhoz, hogy az ábra nézegetése után több kérdésünk legyen, mint előtte.

Minden doboz egyforma. Az egyik egy service, a másik egy csapat, a harmadik egy szerver, és mindhárom ugyanaz a téglalap. Az olvasó találgathat, mit is néz éppen.

A nyilak nem mondanak semmit. Két doboz között húzódik egy nyíl. Ez most egy HTTP-hívás? Event? Adatfolyam? Esetleg csak annyit jelez, hogy a két dolog valahogy összefügg? Felirat nélkül marad a találgatás.

Keverednek a nagyítási szintek. Az egyik sarokban a teljes vállalati rendszertáj, a másikban egy konkrét osztály. Az olvasó folyamatosan váltogatja a nézőpontját, egy idő után pedig inkább megkérdezi a kollégáját, mit akart mondani vele.

Mindenkinek szól egyszerre. A CTO, a fejlesztők, az üzemeltetés, a security csapat és az újonnan érkezők egészen mást kérdeznek. Egyetlen ábra ritkán tud mindegyiküknek jól válaszolni, így a végeredmény általában senkinek sem igazán hasznos.

Elavult, csak ezt senki sem tudja. Másfél éve még naprakész volt. Azóta service-eket vontak össze, írtak újra, váltottak le, az ábra viszont ezt nem követte le. Aki a Confluence egy eldugott oldalán rátalál, jó eséllyel úgy tekint rá, mintha ma is igaz lenne.

Így néz ki mindez együtt, egy kitalált webshop példáján:

Rossz példa · egy kitalált webshop architektúrája

Nyolc egyforma doboz, köztük egy csapat, egy szerver, egy Java osztály és egy külső szolgáltató. A nyilakon nincs felirat, a szaggatott vonal és a kiemelt Kafka doboz jelentését semmi sem magyarázza. A címből annyi derül ki, hogy ez a végleges, második verzió, azt viszont senki sem tudja, mikor készült.

Először a kérdés és a közönség

Első körben semmilyen diagramkészítő eszközt nem nyitnék meg. Két kérdést kell megválaszolni: mit akarunk megmutatni, és kinek.

A "mit" lehet például az, hogyan jut el egy fizetés a rendszerünkön keresztül, vagy milyen külső rendszerektől függünk. Ez két különböző kérdés, és ami a legjobb: senki és semmi sem kötelez arra, hogy ugyanarra az ábrára zsúfoljuk őket.

A közönség legalább ennyire számít. Az új fejlesztőnek szóló diagram más, mint amit a CTO elé teszünk, és ezzel nincs is baj. Ha két közönségnek két ábra kell, rajzoljunk kettőt. Tudom, ezzel megdupláztuk a dokumentációt, cserébe viszont van esély rá, hogy valaki használni is fogja.

Nagyítási szintek: a C4 modell

Az építészek konvencióihoz a szakmánkban talán a C4 modell áll a legközelebb. Simon Brown dolgozta ki, és a lényege egyszerű: a szoftverrendszert négy nagyítási szinten írjuk le, ahogy egy térképen is a kontinenstől az utcáig zoomolunk. Minden szint más kérdésre felel, és egy ábra egyetlen szinten marad.

1. Context (rendszerkörnyezet). A legkülső nézet. A mi rendszerünk itt egyetlen doboz, körülötte a felhasználók és a külső rendszerek, amelyekkel kommunikál. Technológiai részletek nincsenek rajta, így a CTO-tól az üzleti oldalig bárki megérti.

2. Container (konténer). Belenagyítunk a rendszerbe, és megmutatjuk a futtatható, telepíthető egységeket: webalkalmazás, mobilapp, backend service, adatbázis, message broker. Itt jelenik meg a technológia (például Spring Boot, PostgreSQL, Kafka), és az, hogy az egységek hogyan beszélnek egymással. Gyakori félreértés, hogy a container itt Docker konténert jelentene. A C4-ben bármi az, ami önállóan fut vagy adatot tárol.

3. Component (komponens). Egyetlen containert bontunk tovább a fő építőelemeire: modulokra, controllerekre, service rétegekre. Ez már a fejlesztőcsapatnak szól, és akkor érdemes megrajzolni, ha a container elég összetett ahhoz, hogy magyarázat kelljen hozzá.

4. Code (kód). Osztályok, interfészek, táblák. A C4 maga is azt javasolja, hogy ezt a szintet ritkán rajzoljuk kézzel, mert az IDE vagy egy generáló eszköz frissebben megmutatja.

A C4 modell négy szintje · balról jobbra egyre közelebbről

Minden lépés egyetlen dobozba nagyít bele az előző szintről, és ahogy közeledik a kódhoz, úgy szűkül az olvasók köre.

A négy fő szint mellett a C4 néhány kiegészítő nézetet is ismer. A system landscape több rendszer kapcsolatát mutatja egy szervezeten belül. A dynamic diagram egy konkrét folyamat lépéseit követi, például egy fizetés útját. A deployment diagram azt rajzolja le, milyen infrastruktúrán futnak a containerek. Az infra csapat subnetjei tehát ide tartoznak, a Container ábrán csak zajt okoznának.

Egy gyakorlati térkép ahhoz, kinek melyik nézet kell:

Közönség	Mire kíváncsi?	C4 nézet
CTO, üzleti oldal	Milyen rendszerekkel dolgozunk, kiktől függünk?	Context
Új fejlesztő	Milyen service-ek vannak, hogyan beszélnek egymással?	Container
Fejlesztőcsapat	Hogyan épül fel ez a service belülről?	Component
Üzemeltetés, infra	Hol és min fut mindez?	Deployment
Security audit	Hol lépnek át adatok a rendszerhatárokon?	Context és Container, adatfolyamokkal
Termékcsapat, support	Mi történik egy konkrét folyamat során?	Dynamic

A legtöbb csapatnak a Context és a Container szint adja a legtöbb értéket. A Component diagram a bonyolultabb service-eknél segít, a Code szint pedig nyugodtan maradhat a kódban.

Fontos még, hogy a C4 nem ír elő kötelező jelölésrendszert. Dobozokkal és nyilakkal dolgozik, de elvárja, hogy minden elemnek legyen neve, típusa, technológiája és rövid leírása, minden kapcsolatnak felirata, minden ábrának címe és jelmagyarázata.

A rossz diagramokról jellemzően pont ezek hiányoznak.

Feliratok, jelmagyarázat, dátum

A nyilakra van egy meglepően egyszerű szabályom: írjuk rájuk, mi történik. Ha az egyik service HTTP-n hívja a másikat, ez kerüljön a nyílra. Ha eventet publikál Kafkára, akkor az. Egy feliratlan nyíl bármit jelenthet, egy jól feliratozott viszont elmeséli a rendszer egy darabját.

A színekre és a vonaltípusokra ugyanez igaz. Ha valami külön jelentést hordoz, kapjon jelmagyarázatot. Komplett szabványt nem kell írni hozzá, néhány sor is elég, hogy a következő olvasónak ne kelljen kitalálnia, mit jelent a szaggatott vonal.

A cím és a dátum szintén sokat segít, főleg ha valaki hónapokkal később talál rá az ábrára, és el kell döntenie, támaszkodhat-e még rá.

Ugyanaz a webshop, ezekkel a szabályokkal újrarajzolva:

Jobb példa · ugyanaz a webshop, Container nézetben

Az ábra egyetlen kérdésre felel (hogyan megy végig egy fizetés), és végig Container szinten marad. Minden elemnek van neve és technológiája, a nyilakról kiderül, mi szinkron hívás és mi event, a rendszerhatár és a jelmagyarázat pedig eligazít. A Payment csapat, a Szerver 2 és az OrderService.java lekerült róla: ezeknek egy szervezeti ábrán, egy deployment nézetben, illetve egy Component diagramon van a helyük.

Diagram as code: közelebb a kódhoz

Az elavulás ellen az segít a legtöbbet, ha a diagram ott él, ahol a kód. A Mermaid, a PlantUML és a Structurizr szöveges leírásból generál képet, így a diagram bekerülhet a Gitbe, a módosításait pedig ugyanúgy review-zhatjuk egy pull requestben, mint a kódot.

A Structurizr külön említést érdemel, mert kifejezetten a C4-re épül. A rendszert egyszer írjuk le modellként, és ebből generálja a különböző nézeteket. Tíz ábra mögött így egyetlen forrás áll, ami pont a bevezetőben említett csapdán segít: több, közönségre szabott ábrát tarthatunk fenn anélkül, hogy tízszer kellene ugyanazt a változást végigvezetni.

Ha változik a rendszer, a diagram frissítése ugyanannak a munkának a része lehet. Nincs külön grafikus szerkesztő, nincs dobozkeresgélés, és a szétcsúszott nyilakat sem kell helyreállítani.

Korlátai persze ennek is vannak. Az automatikus elrendezés nagyobb ábráknál sokszor csúnya, és nehéz rávenni, hogy azt tegye egymás mellé, amit mi szeretnénk. A naprakészséget sem garantálja: ha senki sem frissíti a forrást, a generált kép is elavul. A karbantartás viszont kevésbé fáj, és könnyebben beilleszthető a fejlesztési folyamatba.

Arra is figyeljünk, hogy ne essünk át a ló túloldalára. Minden apró részletet felesleges kódból generálni, és minden elképzelhető nézőpontról sem kell külön ábra. A cél a használható diagram, egy újabb adminisztratív teher senkinek sem hiányzik.

Hol segít az AI?

A diagram as code-nak van egy mellékhatása, ami az utóbbi időben különösen felértékelődött: a szöveges forrást egy nyelvi modell is tudja olvasni és írni. Néhány gyakorlati felhasználás:

• Első vázlat a kódbázisból. Egy coding agent végigolvassa a repository-t, és elkészíti a Container szintű ábra Mermaid vagy Structurizr forrását. Ritkán tökéletes, kiindulópontnak viszont jóval gyorsabb, mint üres vászonról kezdeni.
• Eltérésfigyelés a pull requestben. Ha egy PR új service-t, queue-t vagy külső hívást vezet be, egy AI review jelezheti, hogy a diagram forrása nem változott vele együtt.
• Közönségre szabott nézetek. Ugyanabból a modellből kérhetünk egyszerűsített Context nézetet a vezetőségnek és részletesebb Container nézetet a csapatnak.
• Térkép az agentnek. Egy jól strukturált, feliratozott architektúraleírás a modellnek is segít eligazodni a rendszerben. Ugyanaz a forrás, amiből az új kolléga tanul, egy coding agent kontextusába is bekerülhet.

Egy figyelmeztetés azonban ide tartozik. Az AI magabiztosan rajzol olyan kapcsolatokat is, amelyek nem léteznek, és néha kihagy olyat, ami kritikus. A generált ábrát ugyanúgy review-zni kell, mint a generált kódot. A kérdést és a közönséget pedig továbbra is nekünk kell eldönteni.

Mielőtt megosztod a következő diagramot

Különleges módszertan nem kell hozzá, elég néhány kérdést feltenni magunknak:

• Világos, mire ad választ az ábra?
• Tudjuk, kinek készült?
• Egyetlen C4 szinten maradt a részletesség?
• Kiderül a nyilakból, mi történik?
• Van jelmagyarázat, ha színek vagy vonaltípusok hordoznak jelentést?
• Van címe és dátuma?
• A forrása ott él, ahol a kód?

Ha ezekre igen a válasz, a diagram jó eséllyel tényleg segít megérteni valamit.

Végül is erről lenne szó. Egy jó architektúradiagramra a megfelelő ember ránéz, és megérti belőle azt, amiért elkészült. Ehhez képest mellékes, hány komponens fér rá, vagy meddig igazgattuk a dobozokat pixelre pontosan.

Ha ebben segítség kell

Ha a diagramjaid rendszeresen több kérdést vetnek fel, mint amennyit megválaszolnak, pont ebben segítek csapatoknak. Gyakorlatias architektúra-workshopokat tartok, ahol a saját rendszereitekből indulunk ki, közösen tisztázzuk a fontos döntéseket, és olyan diagramokat készítünk, amelyek a workshop után is használhatók maradnak.

Ha inkább egy konkrét problémára keresel megoldást, konzultáció keretében átnézem a jelenlegi architektúrát és dokumentációt, segítek megtalálni a hiányosságokat, és együtt végiggondoljuk, hogyan lehetne jobb tervezési döntéseket hozni.