1.6 KiB
1.6 KiB
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 - Website delivery-layer contract:
docs/architecture/website/WEBSITE_CONTRACT.md
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.