ADR-005 — Graf de dependențe prin entitatea-join `SystemDependency`

• Status: Acceptat
• Data: 2026-07-07
• Componentă: SystemDependency, InformationSystem
• Decidenți: Arhitect platformă GStack, teamlead

Context

Sistemele GStack se consumă reciproc: un sistem aplicativ folosește GPass pentru autentificare, GStorage pentru arhivare, GLog pentru logging, GPay pentru plăți. RSI trebuie să răspundă la „ce consumă sistemul X?” și „cine depinde de serviciul Y?” și să alimenteze o matrice de dependențe. O dependență are natură (API, event, date, auth, storage) și poate fi obligatorie sau opțională.

Decizie

Dependențele se modelează ca un graf direcțional, tipizat, printr-o entitate-join SystemDependency cu atribute, între două referințe către InformationSystem:

• system (partea consumatoare) --consumă--> dependsOn (serviciul furnizat);
• atribute: kind ∈ {API, EVENT, DATA, AUTH, STORAGE}, required: boolean, note.

În JDL: două relații ManyToOne de la SystemDependency către InformationSystem (system și dependsOn, ambele required). Muchia este direcțională; „consumat de” se obține navigând invers (InformationSystem{dependent}).

Reguli de business în stratul de servicii:

1. Fără auto-dependență: system ≠ dependsOn (respins la validare).
2. Editarea/ștergerea unei muchii scrie RegistryAudit cu ChangeType = DEPENDENCY_CHANGE.
3. Unicitatea muchiei (system, dependsOn, kind) și politica privind ciclurile rămân decizii deschise (vezi ../db_schema.md §8); v1 permite cicluri (grafuri reale au dependențe reciproce), dar le semnalează în matrice.

Alternative considerate

1. Relație M2M simplă InformationSystem <-> InformationSystem. Respins: nu poate purta atribute (kind, required, note).
2. Câmp JSON cu listă de dependențe pe InformationSystem. Respins: nu e interogabil relațional (matricea, „cine depinde de Y”), nu se poate filtra (filter SystemDependency e cerut în JDL).
3. Serviciu de graf dedicat (Neo4j). Respins: supra-dimensionat; volumul (zeci de sisteme) se pretează perfect la SQL relațional.

Consecințe

Pozitive

• Interogare bidirecțională (consumă / consumat de) și matrice de dependențe direct din SQL.
• Muchii tipizate și cu atribute; filtrabile (JPA Criteria).

Negative / riscuri

• Graf auto-referențial ⇒ atenție la fetch-uri recursive (fără proiectare pot apărea probleme N+1); se folosesc proiecții/DTO și adâncime limitată în vizualizarea matricei.

Legături

• Model: ../../GRegistry.jdl (SystemDependency, DependencyKind)
• Schema: ../db_schema.md §2 (dublu FK auto-referențial)
• Design: ../platform_design.md §5b (activity — actualizare dependență)