Architektúra ako kód: ADR, C4 diagramy a quality gates v CI

Kreslili sme pekne diagramy; o pol roka uz nik nevedel, ci su este pravda. “Prečo sme vlastne prešli na microservices?” Túto otázku som dostal pred 3 rokmi od nového architekta. Nevedel som odpovedať. Človek, ktorý to rozhodol, už v tíme nebol, a v Confluence sme našli len zastaralý diagram z roku 2019.

Od vtedy mám pravidlo: každé architektonické rozhodnutie musí byť zapísané a verzionované. Po 20+ rokoch v softvérovom vývoji som videl tento problém príliš často - rozhodnutia sa strácajú v emailoch, Slack konverzáciách alebo hlavách ľudí, ktorí odídu.

Moja skúsenosť: ADR zaviedol som v 5 rôznych projektoch. C4 diagramy generujem z kódu pomocou Structurizr. CI quality gates bežia v GitHub Actions aj GitLab CI.

V tomto článku vám ukážem systém, ktorý funguje: ADR (Architecture Decision Records) + C4 diagramy + automatizácia v CI. Nie teóriu, ale konkrétne šablóny, workflow a quality gates, ktoré môžete zaviesť zajtra.

Prečo dokumentácia zlyháva

Väčšina tímov pozná tieto problémy:

• Dokumentácia hnije - napísaná raz, nikdy neaktualizovaná
• Rozhodnutia sa strácajú - “prečo sme to vlastne spravili takto?”
• Onboarding bolí - nový človek potrebuje týždne na pochopenie systému
• Architekt = bottleneck - jeden človek drží všetky znalosti v hlave

Riešenie nie je písať viac dokumentácie. Riešenie je písať správnu dokumentáciu a automatizovať jej údržbu.

Základné stavebné kamene

Architecture Decision Records (ADR)

ADR je krátky dokument, ktorý zachytáva jedno architektonické rozhodnutie. Nie román, ale štruktúrovaný záznam s týmito povinnými sekciami:

# ADR-001: Použitie PostgreSQL ako primárnej databázy

## Status
Accepted

## Context
Potrebujeme relačnú databázu pre core business dáta.
Máme skúsenosti s PostgreSQL aj MySQL v tíme.

## Decision
Použijeme PostgreSQL 16 s TimescaleDB extension pre time-series dáta.

## Alternatives Considered
1. MySQL 8 - menej pokročilé JSON funkcie
2. MongoDB - nepotrebujeme flexibility schémy, potrebujeme ACID
3. CockroachDB - overhead pre náš scale

## Consequences
### Positive
- Silná podpora JSON, full-text search, GIS
- Lepšia podpora pre analytics workloads

### Negative
- Vyššia komplexita ops oproti managed MySQL
- Menej kandidátov s hlbokou PostgreSQL znalosťou

### Risks
- TimescaleDB vendor lock-in pre time-series časť

Anti-patterns, ktorým sa vyhnite:

• ADR ako román (max 1-2 strany)
• Chýbajúce alternatívy (vždy uviesť aspoň 2-3)
• Žiadne dôsledky (to je najpodstatnejšia časť!)

C4 Model

C4 model definuje 4 úrovne abstrakcie pre architektonické diagramy:

1. Context - systém a jeho okolie (používatelia, externé systémy)
2. Container - aplikácie, databázy, message brokery
3. Component - vnútorná štruktúra jedného kontajnera
4. Code - triedy, moduly (zvyčajne generované z kódu)

Kedy ktorý level použiť:

Repo štruktúra

/docs
  /adr
    /0001-use-postgresql.md
    /0002-event-driven-architecture.md
    /0003-kubernetes-deployment.md
    /index.md              # automaticky generovaný zoznam
  /c4
    /context.puml          # alebo .mmd pre Mermaid
    /containers.puml
    /components
      /order-service.puml
      /payment-service.puml
  /rfcs                    # pre väčšie zmeny pred implementáciou
    /0001-migrate-to-grpc.md

Konvencie názvov:

• ADR: NNNN-kebab-case-title.md
• Číslujte sekvenčne, nikdy neprečíslujte
• Superseded ADR označte v statuse, ale nemažte

Prepojenie ADR a C4

Každé ADR by malo odkazovať na relevantné C4 diagramy:

## Context
Potrebujeme riešiť asynchrónnu komunikáciu medzi službami.
Viď [Container diagram](/docs/c4/containers.puml) - sekcia Message Broker.

## Decision
Implementujeme event-driven architektúru s Apache Kafka.

A naopak, C4 diagramy môžu odkazovať na ADR:

' Ref: ADR-002 Event-Driven Architecture
Container(kafka, "Apache Kafka", "Event streaming platform")

Docs-as-Code Workflow

PR Review Checklist

Pri každom PR, ktorý mení architektúru:

• Existuje alebo je vytvorený ADR pre toto rozhodnutie?
• Je ADR schválený (Status: Accepted)?
• Sú aktualizované relevantné C4 diagramy?
• Sú odkazy medzi ADR a C4 správne?
• Je ADR linkovaný z kódu (komentár, README)?

Vlastníctvo bez bottlenecku

Architekt NIE JE gatekeeper. Architekt je:

• Facilitátor - pomáha tímu písať ADR
• Reviewer - dáva feedback, nie veto
• Kurátor - udržuje konzistenciu

Pravidlo: Každý môže navrhnúť ADR. Schválenie vyžaduje review od 2 seniorov + architekta.

Automatizácia v CI (Quality Gates)

Tu je sila tohto prístupu. CI pipeline automaticky:

1. Lintovanie Markdown

# .github/workflows/docs.yml
- name: Lint ADRs
  uses: DavidAnson/markdownlint-cli2-action@v14
  with:
    globs: 'docs/adr/*.md'

2. Kontrola povinných sekcií

#!/bin/bash
# scripts/validate-adr.sh
for file in docs/adr/*.md; do
  for section in "## Status" "## Context" "## Decision" "## Consequences"; do
    if ! grep -q "$section" "$file"; then
      echo "ERROR: $file missing $section"
      exit 1
    fi
  done
done

3. Kontrola linkov

- name: Check links
  uses: lycheeverse/lychee-action@v1
  with:
    args: --verbose docs/

4. Generovanie diagramov

- name: Generate C4 diagrams
  run: |
    plantuml -tpng docs/c4/*.puml
    # alebo pre Mermaid:
    # mmdc -i docs/c4/*.mmd -o docs/c4/output/

5. Publikovanie dokumentácie

- name: Deploy docs
  uses: peaceiris/actions-gh-pages@v3
  with:
    publish_dir: ./docs

Definition of Done pre architektonické zmeny

Kedy MUSÍ vzniknúť ADR:

• Pridanie novej služby/kontajnera
• Zmena databázovej technológie
• Nový integračný pattern (sync → async)
• Bezpečnostné rozhodnutia (autentifikácia, autorizácia)
• Významná zmena API kontraktu

Kedy STAČÍ update C4:

• Pridanie nového endpointu do existujúcej služby
• Refaktoring bez zmeny vonkajšieho správania
• Performance optimalizácie

Ako to zaviesť bez revolúcie

Týždeň 1-2: Pilot

1. Vyberte 5 najpálčivejších rozhodnutí z posledného roku
2. Napíšte k nim ADR (retrospektívne je OK)
3. Vytvorte Context a Container C4 diagram

Týždeň 3-4: Feedback

1. Prezentujte tímu
2. Zbierajte feedback na šablóny
3. Upravte podľa potrieb

Týždeň 5+: Roll-out

1. Pridajte do Definition of Done
2. Zapnite CI checks (najprv warning, potom error)
3. Iterujte

Metriky úspechu

Ako zistíte, že to funguje:

• Onboarding čas - nový developer produktívny za X dní (target: -30%)
• Incidenty z nepochopenia - “nevedel som, že to tak funguje” (target: -50%)
• Lead time na zmenu - od rozhodnutia po deploy (target: stabilný alebo nižší)
• ADR coverage - % major komponentov s ADR (target: 80%+)

Šablóny na stiahnutie

Pripravil som pre vás:

• ADR šablóna (Markdown)
• C4 PlantUML starter kit
• GitHub Actions workflow
• PR review checklist

Záver

Living documentation nie je o písaní viac dokumentácie. Je o písaní správnej dokumentácie na správnom mieste s automatickou validáciou.

Začnite malým krokom: napíšte dnes 5 ADR k najdôležitejším rozhodnutiam vo vašom projekte. Zajtra pridajte CI check. O týždeň budete mať systém, ktorý vám ušetrí hodiny pri každom onboardingu a incidente.

Váš ďalší krok: Identifikujte 5 architektonických rozhodnutí z posledného roka a napíšte k nim ADR. Použite šablónu vyššie.

Často kladené otázky (FAQ)

Koľko ADR by mal mať projekt?

Záleží na veľkosti projektu. Pre typický microservices projekt očakávajte 20-50 ADR po 2 rokoch. Nepíšte ADR pre každé rozhodnutie - len pre tie, ktoré sú ťažko reverzibilné alebo majú významný dopad.

Kto by mal písať ADR?

Každý, kto robí architektonické rozhodnutie. Nie je to práca len pre architekta. Senior developer, ktorý navrhuje nový integračný pattern, by mal napísať ADR sám.

Čo ak sa rozhodnutie ukáže ako zlé?

Nikdy nemažte staré ADR. Namiesto toho napíšte nové ADR s odkazom na pôvodné a vysvetlite, prečo meníte rozhodnutie. Status pôvodného ADR zmeňte na “Superseded by ADR-XXX”.

Aký nástroj použiť na C4 diagramy?

PlantUML alebo Mermaid sú najlepšie voľby - sú text-based, takže ich môžete verzovať v Git. Structurizr je komerčná alternatíva s lepším UI.

Súvisiace články

• CI/CD pre monorepo: Rýchlosť, cache, selektívne testy a supply-chain bezpečnosť - Ako automatizovať quality gates a CI/CD pipeline pre vašu architektúru
• Zero-downtime migrácie PostgreSQL: Expand/Contract, backfill a rollback stratégie - Praktický playbook pre bezpečné databázové migrácie v produkcii