Skip to content

ADR_00022: WebAPI a ErpAPI jako BFF (Backend for Frontend)

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

Context

V architektuře e-shopu existují různé vstupní body do systému:

  • WebAPI – frontend (UI, e-shop, zákaznické rozhraní)
  • ErpAPI – interní systémy (ERP, backoffice, administrativa)
  • gRPC / Worker – doménová logika, eventy, orchestrace

Dle rozhodnutí v ADR_00003 jsou tyto vstupy řešeny jako oddělené projekty / repozitáře.

Web i ERP mají odlišné: - požadavky na výkon, - strukturu dat, - SLA, - způsob autentizace, - chování vůči doméně.

Je tedy nutné jasně definovat jejich roli v architektuř a tou je Channel, jelikož to jsou pouze vstupní body.

Decision

WebAPI a ErpAPI jsou BFF (Backend For Frontend)

  • WebAPI a ErpAPI jsou pouze BFF vrstvy
  • Neobsahují doménovou logiku
  • Nevlastní agregáty
  • Neprovádí změny stavu přímo

Jejich úloha je:

  • mapovat požadavky klienta
  • postavit nad sdílenou doménovou DB read modely dle potřeb klientů
  • validovat vstupy,
  • volat autoritativní službu (gRPC) při mutaci dat

Pravidla

WebAPI / ErpAPI:

mohou - číst z read modelů
- volat gRPC službu vpro případnou změnu
- provádět validaci vstupu
- optimalizovat payload pro UI / ERP

nesmí - měnit stav agregátu
- obsahovat business logiku
- publikovat eventy
- obcházet gRPC / worker vrstvu
- mít vlastní doménový model

Změna stavu systému

Každá změna stavu musí:

  1. projít přes gRPC / Worker
  2. být zpracována v agregátu
  3. vyvolat domain event
  4. být propagována pomocí Kafka / Outbox

WebAPI ani ErpAPI jsou zdrojem pravdy neboť čtou z doménové databáze spravované Workerem + RPC službou.

Vazba na architekturu

Vrstva Odpovědnost
WebAPI BFF pro frontend
ERrpAPI BFF pro interní systémy
gRPC / Worker Doménová logika, agregáty
Kafka Event-driven komunikace
Read modely Projekce pro čtení

Consequences

Pozitiva

  • Jasné oddělení odpovědností
  • Žádná duplikace doménové logiky
  • Snadná změna UI bez dopadu na doménu
  • Podpora CQRS
  • Lepší testovatelnost

Negativa

  • Nutnost udržovat více vrstev
  • Přísná disciplína při návrhu API
  • Vyšší důraz na dokumentaci a kontrakty

Rationale

Rozhodnutí Důvod
WebAPI = BFF Optimalizace pro frontend
ERPAPI = BFF Oddělení interních integrací
Bez doménové logiky Zachování integrity agregátů
gRPC/Worker jako místo změn Zachování jednotného místa pro mutaci