# 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.