docs

docs/architecture/shared/BLOCKERS_AND_GUARDS.md

@@ -0,0 +1,60 @@
+# Blockers and Guards (Shared Contract)
+
+This document defines the **shared contract** for Blockers (website UX) and Guards (API enforcement).
+
+If a more specific document conflicts with this one, this shared contract wins.
+
+Related:
+
+- API authorization: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1)
+- Website delivery-layer contract: [`docs/architecture/website/WEBSITE_CONTRACT.md`](docs/architecture/website/WEBSITE_CONTRACT.md:1)
+
+## 1) Core principle (non-negotiable)
+
+Guards enforce. Blockers prevent.
+
+- Guards protect the system.
+- Blockers protect the UX.
+
+There are no exceptions.
+
+## 2) Definitions (strict)
+
+### 2.1 Guard (API)
+
+A Guard is an **API mechanism** that enforces access or execution rules.
+
+If a Guard denies execution, the request does not reach application logic.
+
+### 2.2 Blocker (Website)
+
+A Blocker is a **website mechanism** that prevents an action from being executed.
+
+Blockers exist solely to improve UX and reduce unnecessary requests.
+
+Blockers are not security.
+
+## 3) Responsibility split (hard boundary)
+
+| Aspect | Blocker (Website) | Guard (API) |
+|---|---|---|
+| Purpose | Prevent execution | Enforce rules |
+| Security | ❌ No | ✅ Yes |
+| Authority | ❌ Best-effort | ✅ Final |
+| Reversible | ✅ Yes | ❌ No |
+| Failure effect | UX feedback | HTTP error |
+
+## 4) Naming rules (hard)
+
+- Website uses `*Blocker`.
+- API uses `*Guard`.
+- Never mix the terms.
+- Never implement Guards in the website.
+- Never implement Blockers in the API.
+
+## 5) Final rule
+
+If it must be enforced, it is a Guard.
+
+If it only prevents UX mistakes, it is a Blocker.
+