ADR 0001 — Platform & runtime choice

Status. Accepted (2026-05-27) Authors. [email protected]

Context

sigmashake-docs is a SigmaShake monorepo service. We needed to pick a runtime that matches the service's role in the stack — edge HTTP API vs. local operator tool vs. background BEAM cluster — without proliferating incompatible deployment targets.

Decision

Amended 2026-10-11. The original text named Cloudflare Workers, D1 / KV / R2, and Secrets Store. The site is static Cloudflare Pages. It has no Worker, no D1 database, no KV namespace, no R2 bucket, and no Secrets Store binding (see wrangler.toml and the security whitepaper). The text now matches the deployed site.

Run sigmashake-docs as a static site on Cloudflare Pages.

• Docusaurus pre-renders every page to build/ at build time.
• Cloudflare Pages serves the static files from Cloudflare's edge network.
• The site has no runtime logic and no storage layer.
• The site holds no secrets at runtime. The deploy command uses the operator's Cloudflare credentials.
• A runtime HTTP API, if one is ever needed, belongs in a separate service (see sigmashake-fleet for the dispatcher Worker pattern). It does not belong in this project.

Alternatives considered

1. Bun/Node service on a container. Lower platform lock-in, but needs machine provisioning and gives no gain for pre-rendered pages.
2. Long-running Elixir cluster. Better for stateful workloads; not needed for this surface.
3. Cloudflare Worker with D1 / KV / R2. This was the original decision (2026-05-27). The docs site has no dynamic data, so it was never built.

Consequences

• We accept the Cloudflare-platform lock-in.
• Operational visibility is tied to Cloudflare's observability stack.
• Deploys use wrangler pages deploy — no manual machine provisioning (see ADR 0003).

Revisit

The platform choice is revisited when:

• The service grows past 10× its current request rate.
• A platform-specific dependency goes EOL.
• A customer's data-residency / compliance requirement forces a move.