blockers

docs/architecture/BLOCKER_GUARDS.md

@@ -0,0 +1,154 @@
+Blockers & Guards
+
+This document defines clear, non-overlapping responsibilities for Blockers (frontend) and Guards (backend).
+The goal is to prevent semantic drift, security confusion, and inconsistent implementations.
+
+⸻
+
+Core Principle
+
+Guards enforce. Blockers prevent.
+	•	Guards protect the system.
+	•	Blockers protect the UX.
+
+There are no exceptions to this rule.
+
+⸻
+
+Backend — Guards (NestJS)
+
+Definition
+
+A Guard is a backend mechanism that enforces access or execution rules.
+If a Guard denies execution, the request does not reach the application logic.
+
+In NestJS, Guards implement CanActivate.
+
+⸻
+
+Responsibilities
+
+Guards MAY:
+	•	block requests entirely
+	•	return HTTP errors (401, 403, 429)
+	•	enforce authentication and authorization
+	•	enforce rate limits
+	•	enforce feature availability
+	•	protect against abuse and attacks
+
+Guards MUST:
+	•	be deterministic
+	•	be authoritative
+	•	be security-relevant
+
+⸻
+
+Restrictions
+
+Guards MUST NOT:
+	•	depend on frontend state
+	•	contain UI logic
+	•	attempt to improve UX
+	•	assume the client behaved correctly
+
+⸻
+
+Common Backend Guards
+	•	AuthGuard
+	•	RolesGuard
+	•	PermissionsGuard
+	•	ThrottlerGuard (NestJS)
+	•	RateLimitGuard
+	•	CsrfGuard
+	•	FeatureFlagGuard
+
+⸻
+
+Summary (Backend)
+	•	Guards decide
+	•	Guards enforce
+	•	Guards secure the system
+
+⸻
+
+Frontend — Blockers
+
+Definition
+
+A Blocker is a frontend mechanism that prevents an action from being executed.
+Blockers exist solely to improve UX and reduce unnecessary requests.
+
+Blockers are not security mechanisms.
+
+⸻
+
+Responsibilities
+
+Blockers MAY:
+	•	prevent multiple submissions
+	•	disable actions temporarily
+	•	debounce or throttle interactions
+	•	hide or disable UI elements
+	•	prevent navigation under certain conditions
+
+Blockers MUST:
+	•	be reversible
+	•	be local to the frontend
+	•	be treated as best-effort helpers
+
+⸻
+
+Restrictions
+
+Blockers MUST NOT:
+	•	enforce security
+	•	claim authorization
+	•	block access permanently
+	•	replace backend Guards
+	•	make assumptions about backend state
+
+⸻
+
+Common Frontend Blockers
+	•	SubmitBlocker
+	•	AuthBlocker
+	•	RoleBlocker
+	•	ThrottleBlocker
+	•	NavigationBlocker
+	•	FeatureBlocker
+
+⸻
+
+Summary (Frontend)
+	•	Blockers prevent execution
+	•	Blockers improve UX
+	•	Blockers reduce mistakes and load
+
+⸻
+
+Clear Separation
+
+Aspect	Blocker (Frontend)	Guard (Backend)
+Purpose	Prevent execution	Enforce rules
+Security	❌ No	✅ Yes
+Authority	❌ Best-effort	✅ Final
+Reversible	✅ Yes	❌ No
+Failure effect	UI feedback	HTTP error
+
+
+⸻
+
+Naming Rules (Hard)
+	•	Frontend uses *Blocker
+	•	Backend uses *Guard
+	•	Never mix the terms
+	•	Never implement Guards in the frontend
+	•	Never implement Blockers in the backend
+
+⸻
+
+Final Rule
+
+If it must be enforced, it is a Guard.
+
+If it only prevents UX mistakes, it is a Blocker.