Skip to content

ADR_00001: Core domény – komunikační kanály a integrační vzory

Status: Proposed / Accepted
Date: 2025-12-28

Context

V našem e-shopu používáme DDD s Core, Supporting, Generic doménami a Channely.
Mezi core domény patří například:

  • Checkout
  • Order
  • Stock
  • Pricing

Tyto domény musí komunikovat:

  • s WEB klienty,
  • s interními systémy (ERP),
  • mezi sebou navzájem (machine-to-machine),
  • a podporovat event-driven orchestraci.

Cílem je mít jasně oddělené integrační kanály, vysokou spolehlivost a možnost dalšího rozšiřování bez zásahu do doménové logiky.

Decision

Pro core domény je zavedena následující integrační architektura:

REST API pro WEB klienty

  • Každá core doména poskytuje veřejné REST endpointy.
  • Slouží pro:
  • webový frontend,
  • synchronní operace,
  • dotazy a příkazy.

Vlastnosti:

  • Primárně synchronní komunikace,
  • zaměřeno na UX,
  • stabilní kontrakt.

REST API pro ERP

  • Samostatné REST endpointy určené pro ERP.
  • Oddělené od webového API:
  • jiný path (/api/erp/...),
  • nebo jiná verze.

Důvody:

  • oddělení změn frontendu a ERP,
  • stabilní integrační rozhraní,
  • možnost odlišného řízení bezpečnosti a případně verzování.

Worker + Inbox / Outbox pattern

Každá doména implementuje asynchronní workery, které:

  • čtou inbox eventy z ostatních domén,
  • publikují outbox eventy,
  • zajišťují:
    • spolehlivé doručení
    • retry mechanizmy
    • idempotenci
    • eventual consistency

Použití:

  • integrace mezi doménami
  • synchronizace stavů
  • orchestrace procesů

gRPC pro machine-to-machine komunikaci

  • Použito pro:
    • nízkou latenci,
    • vysoký výkon,
    • streaming,
    • interní orchestraci.
    • Jasný interface

Consequences

Pozitiva

  • Jasné oddělení synchronní a asynchronní komunikace
  • Definované integrační rozhraní pro každý typ klienta
  • Snadná rozšiřitelnost systému
  • Podpora event-driven architektury
  • Připravenost na CQRS

Negativa / náklady

  • Vyšší komplexita systému
  • Nutnost:
    • monitoringu,
    • observability,
    • retry mechanismů,
    • DLQ / error handlingu

Rationale

Rozhodnutí Odůvodnění
REST pro WEB Jednoduché, standardní API pro frontend
REST pro ERP Oddělení integrací a stabilní kontrakt
Inbox / Outbox Spolehlivá asynchronní komunikace
Event-driven přístup Podpora CQRS a loose coupling
gRPC Nízká latence a efektivní M2M komunikace

Considered Alternatives

  • Použití microservices pro každou doménu

    • Pozitiva: nezávislé deploye
    • Negativa:
      • složitější orchestrace
      • více operational overhead
      • Nutnost distribuovaných transakcí

  • Použití shared database místo eventů

    • Pozitiva: jednoduché dotazy napříč doménami
    • Negativa: silný coupling, ztráta auditability

  • Monolit pro celkovou orchestraci

    • Pozitiva:
      • Jednodušší release
      • Jednodušší verzování
    • Negativa:
      • Nemožnost škálovat
      • Složité oddělování integračních rozhraní v případě security etc