Non-Functional Requirements — quarry.team (next-gen)

Status: Accepted
Owner: Engineering
Last updated: 2026-06-06

These are the quality attributes the site must satisfy. They are enforced as CI gates where possible (ADR 0012, ADR 0009).

1. Performance

Lighthouse ~100 for Performance (and the other categories), enforced via Lighthouse CI budgets against preview builds. Regressions fail the build.
Core Web Vitals within “good” thresholds on real-user data (Cloudflare Web Analytics):
- LCP ≤ 2.5 s
- INP ≤ 200 ms
- CLS ≤ 0.1
JavaScript budget: content pages ship zero framework runtime by default; client JS is limited to explicit islands (mobile nav, search UI, form widgets) and kept minimal (ADR 0002). Any new island that increases the shipped JS budget is justified in review.
Delivery: static output, edge-cached globally on Cloudflare (ADR 0006); responsive, optimized images generated at build by Astro’s image pipeline from git-committed sources kept under a byte budget (ADR 0004); modern formats; fonts loaded without layout shift.

This document sets the intent (zero-JS-by-default, CWV “good”, Lighthouse ~100); the numeric gates live in CI. Lighthouse CI (lighthouserc.cjs) enforces category-score thresholds and the CWV metric caps above, per page class; the raster byte budget is enforced separately by the image-pipeline check (scripts/images.mjs, run in CI as pnpm images:check). We do not restate those numeric budgets here.

2. Accessibility

WCAG 2.2 AA conformance is the bar.
Automated axe checks on key templates run in CI; failures gate merges.
Requirements include: semantic landmarks and heading order; full keyboard operability with a visible focus indicator; color contrast meeting AA against the “Quarried” palette; meaningful alt text; accessible form labels, errors, and status messaging; respect for prefers-reduced-motion.
Automation is necessary but not sufficient — periodic manual audits (keyboard + screen reader) supplement it.

3. Security

No secrets in the repository. Credentials live in GitHub Actions secrets and Cloudflare Worker secrets (e.g. TURNSTILE_SECRET, RESEND_API_KEY) — see SECURITY.md, ADR 0008.
Cloudflare WAF in front of the site and form endpoints, including rate-limiting on /api/*; Turnstile on all submissions, verified server-side.
Server-side validation on the /api/* form routes; no public read endpoints on the data tier (ADR 0014).
Transport: HTTPS everywhere (automatic TLS at the edge); a strict, reviewed Content-Security-Policy with no 'unsafe-*' source expression in any directive — every inline script and style is SHA-256 hash-pinned at build, object-src 'none', third-party UI confined to allowlisted iframes (ADR 0015) — plus standard security headers (HSTS, X-Content-Type-Options, Referrer-Policy, frame-ancestors 'none'). Enforced as a CI gate (unit + build + e2e). Because the form endpoints are same-origin /api/* routes on the Worker, the CSP needs no cross-origin API allowance.
Dependencies: pnpm with a committed frozen lockfile; routine dependency review.
Responsible disclosure: security@quarry.team (SECURITY.md).

4. Privacy

No cookie/consent banner; no third-party tracking. Analytics is cookieless Cloudflare Web Analytics (ADR 0010).
Personal data (contact/careers leads) is confined to the Cloudflare D1 data tier (the form_submissions table), with point-in-time recovery via D1 Time Travel and a defined retention policy, and is never exposed via a public endpoint.
Data handling is consistent with Quarry’s own client-facing data-practice positioning.

5. SEO

Per-page canonical URLs, titles, meta descriptions, OG/Twitter cards.
Valid JSON-LD (Organization, article/creative-work, breadcrumbs where relevant).
Generated sitemap.xml referenced by robots.txt; llms.txt for AI discoverability.
URL continuity: legacy /cases/* → /work/* 301s; /blog/* unchanged (ADR 0011).

6. i18n-readiness

The site ships English-only in this phase, but is built to not preclude localization: no hardcoded copy baked into logic where avoidable, locale-tolerant routing assumptions, and a content model that could be extended per-locale. No translated content is in scope now (see PRD scope).

7. Browser support

Current and previous major versions of evergreen browsers: Chrome, Edge, Firefox, Safari (desktop and mobile), including iOS Safari and Android Chrome.
Progressive enhancement: core content and navigation work without JavaScript; islands enhance rather than gate. No support obligation for legacy non-evergreen browsers (e.g. IE11).

8. Reliability & operability

Public site has no single point of failure — prerendered assets served from Cloudflare’s global edge.
Infrastructure is reproducible via Terraform; deploys are automated and rollback is defined (docs/runbooks/deploy.md).
The data tier (Cloudflare D1) has point-in-time recovery via Time Travel and a documented incident path (docs/runbooks/incident-response.md).