ramadanproject/docs/decisions/001-public-grid-viewer.md

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.