# Decision — 001 Public Grid Viewer

Date: 2026-01-03  
Status: Accepted

## Context
We need a responsive “public grid viewer” that displays a master image with a selectable grid overlay.
Selection coordinates must be validated server-side and mapped to cell units consistently to support reservations and later payment/rendering flows.

## Decision
1. **Canvas-based rendering** (Konva/canvas) is used for the grid and selection overlay.
   - We avoid rendering thousands of DOM nodes.
2. **Server is the source of truth** for pixel→cell mapping and validation.
   - A Form Request validates the payload.
   - A dedicated mapper/service converts pixels to cell units.
3. **Reservations are DB-backed** with expiration.
   - Conflicts return 409.
   - Holds are pruned via a scheduled command (documented in `SCHEDULER.md`).
4. **Cache busting** uses a `master_version` (or equivalent) rather than relying on browser behavior.

## Consequences
- Frontend selection must snap to cell units and display “blocked” areas using availability data.
- All future payment/checkout flows will rely on reservation state rather than client-side assumptions.
- The scheduler must run in production to prevent stale holds from blocking availability.

## Alternatives considered
- DOM grid (rejected): too slow/heavy at scale.
- Client-only mapping (rejected): inconsistent and insecure for checkout/locking.
- No scheduler (rejected): stale reservations degrade UX and correctness.