Skip to content

Open-source status page, incident response and uptime monitoring

docs: first adr (#2188)

Thibault Le Ouay43ea444e9daa
diff --git a/docs/adr/0000-use-markdown-any-decision-records.md b/docs/adr/0000-use-markdown-any-decision-records.md
new file mode 100644
index 000000000..bdae63f27
--- /dev/null
+++ b/docs/adr/0000-use-markdown-any-decision-records.md
@@ -0,0 +1,64 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# Use Markdown Any Decision Records (MADR)
+
+## Context and Problem Statement
+
+openstatus is a pnpm + Turborepo monorepo spanning a Next.js dashboard, a Hono
+API server, a Go checker, and ~25 shared packages. Architecturally significant
+decisions — the services layer, API-key scopes, the move to Effect-based
+fetchers, framework choices — currently live only in PR descriptions, commit
+messages, and `CLAUDE.md`. That makes the *why* behind a decision hard to find
+and easy to lose when contributors change.
+
+How should we record architecturally significant decisions so the reasoning,
+the alternatives, and the trade-offs stay discoverable over time?
+
+## Decision Drivers
+
+- The reasoning behind a decision must outlive the PR that introduced it.
+- New contributors need a single place to learn "why is it built this way?".
+- The format must be lightweight enough that writing an ADR is not a chore.
+- Records should be diff-friendly and reviewable like code.
+
+## Considered Options
+
+- Markdown Any Decision Records (MADR)
+- Nygard-style lightweight ADRs
+- A wiki / Notion page for architecture decisions
+- Keep relying on PR descriptions and `CLAUDE.md`
+
+## Decision Outcome
+
+Chosen option: "Markdown Any Decision Records (MADR)", because it lives in the
+repo next to the code, is reviewed through the normal PR process, and its
+template explicitly prompts for *decision drivers* and *considered options* —
+the parts most often lost when a decision is only captured in a commit message.
+
+ADRs are stored in `docs/adr/`, named `NNNN-kebab-case-title.md` with a
+zero-padded, monotonically increasing number. `template.md` is the MADR
+template. This file, ADR-0000, is the first record.
+
+### Consequences
+
+- Good, because decision history is versioned, searchable, and offline.
+- Good, because the template's prompts produce consistent, comparable records.
+- Bad, because contributors must remember to write an ADR for significant
+ decisions; this is mitigated by the checklist in `README.md`.
+
+### Confirmation
+
+A new ADR is added under `docs/adr/` whenever a decision matches the "When to
+write an ADR" criteria in `docs/adr/README.md`, and is reviewed in the same PR
+as (or just before) the change it describes.
+
+## More Information
+
+- MADR project: https://adr.github.io/madr/
+- ADR overview: https://adr.github.io/
+- `CLAUDE.md` remains the home for *current* conventions an agent must follow;
+ ADRs explain *why* those conventions exist and what was rejected.
diff --git a/docs/adr/0001-business-logic-lives-in-the-services-layer.md b/docs/adr/0001-business-logic-lives-in-the-services-layer.md
new file mode 100644
index 000000000..39a6a693d
--- /dev/null
+++ b/docs/adr/0001-business-logic-lives-in-the-services-layer.md
@@ -0,0 +1,126 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# Workspace business logic lives in a framework-agnostic services layer
+
+## Context and Problem Statement
+
+openstatus exposes the same workspace-scoped operations — create a monitor,
+update a status report, delete an integration — through several entry points:
+tRPC handlers in the Next.js dashboard, Hono routes in `apps/server`, the MCP
+server, and background jobs in `apps/workflows`.
+
+Originally that logic lived inside the tRPC routers. Every other entry point
+either duplicated it or could not reach it at all, and there was no consistent
+place to enforce cross-cutting concerns: workspace isolation, an audit trail,
+and API-key permission checks. The dashboard also runs tRPC on the Next.js Edge
+runtime, so any shared code must avoid `node:*` imports.
+
+Where should workspace-scoped business logic live so it is reusable across
+every entry point and enforces these concerns uniformly?
+
+## Decision Drivers
+
+- The same operation must be callable from tRPC, Hono, MCP, and jobs without
+ duplication.
+- Every mutation must be workspace-scoped — no cross-workspace data access.
+- Every mutation must produce an audit record, atomically with the change.
+- API keys carry `read`/`write` scopes that must gate every write.
+- Shared code must be Edge-safe (no `node:*` built-ins).
+- Errors must map cleanly onto each transport (tRPC codes, HTTP statuses).
+
+## Considered Options
+
+- Keep business logic in tRPC routers (status quo)
+- Extract a dedicated, framework-agnostic `packages/services` layer
+- Route all dashboard mutations through the Hono `apps/server` HTTP API
+
+## Decision Outcome
+
+Chosen option: "Extract a dedicated, framework-agnostic `packages/services`
+layer", because it is the only option that lets every entry point share one
+implementation while making workspace scoping, auditing, and scope enforcement
+structurally hard to skip. Transports (tRPC, Hono, MCP) become thin adapters:
+validate input, call a service verb, map errors.
+
+The migration was deliberate and incremental, one domain per PR (#2100
+scaffolded the package; #2101 onward migrated `status-report`, `maintenance`,
+and the rest; #2118 added the audit-log infrastructure).
+
+The shape of the layer:
+
+- **One file per verb** under `packages/services/src/<entity>/`
+ (`create.ts`, `update.ts`, `remove.ts`, …), re-exported from the entity's
+ `index.ts`. Callers import from `@openstatus/services/<entity>`.
+- **Standard signature:**
+ `verbEntity(args: { ctx: ServiceContext; input: VerbInput })`.
+ `ServiceContext` carries `workspace`, `actor`, and an optional `db`/tx.
+- **`requireScope(ctx, "write")`** is the first line of every write verb,
+ before input parsing.
+- **`withTransaction(ctx, fn)`** reuses an outer transaction if one was
+ threaded through `ctx.db`, otherwise opens one.
+- **Workspace scoping is mandatory** — `getXInWorkspace` fetch-or-throw
+ helpers in each entity's `internal.ts`.
+- **`emitAudit(tx, ctx, entry)`** runs inside the same transaction; a failed
+ audit insert rolls back the mutation (fail-closed).
+- **Errors** are `ServiceError` subclasses (`NotFoundError`, `ForbiddenError`,
+ …); routers convert them with `toTRPCError`.
+
+### Consequences
+
+- Good, because tRPC, Hono, MCP, and jobs share one tested implementation.
+- Good, because auditing and scope checks are uniform and hard to bypass — a
+ missing `emitAudit` or `requireScope` is treated as a review blocker.
+- Good, because the layer is Edge-safe by construction (e.g. `deepEqual` is
+ hand-rolled because `node:util` is unavailable on Edge).
+- Bad, because routers and services are two layers to navigate instead of one.
+- Bad, because the conventions (ctx threading, transaction reuse, audit
+ snapshots, secret stripping) have a learning curve; `CLAUDE.md` and the
+ `__tests__/` suites document them.
+- Neutral, because inline DB access in a router still compiles — enforcement
+ is by convention and review, not by the type system.
+
+### Confirmation
+
+Each verb has a suite under `packages/services/src/<entity>/__tests__/` that
+asserts the audit side-effect via `expectAuditRow(...)` and includes a
+`"rejects read-only actor"` case built with `makeApiKeyCtx(...)`. Code review
+rejects business logic added directly to a router.
+
+## Pros and Cons of the Options
+
+### Keep business logic in tRPC routers
+
+- Good, because there is only one layer and no extra indirection.
+- Bad, because Hono, MCP, and jobs cannot reuse it without duplication.
+- Bad, because cross-cutting concerns are enforced ad hoc, if at all.
+- Bad, because tRPC types leak into code that non-tRPC callers must use.
+
+### Extract a `packages/services` layer
+
+- Good, because one implementation serves every transport.
+- Good, because workspace scoping, audit, and scope checks have one home.
+- Good, because it is transport- and Edge-runtime agnostic.
+- Bad, because it adds a layer and a set of conventions to learn.
+
+### Route dashboard mutations through the Hono HTTP API
+
+- Good, because there would be a single backend codebase.
+- Bad, because every dashboard mutation pays a network hop and loses
+ end-to-end type inference.
+- Bad, because jobs and MCP would still need a non-HTTP path, so the
+ duplication problem returns.
+
+## More Information
+
+- Package: `packages/services/` — see `src/context.ts` (`ServiceContext`,
+ `withTransaction`), `src/audit/emit.ts`, `src/auth/require-scope.ts`.
+- Audit action names follow `{entity}.{verb}` and are declared in the
+ discriminated union at
+ `packages/db/src/schema/audit_logs/validation.ts`.
+- Conventions an agent must follow are summarized in `CLAUDE.md`
+ ("Services & Audit Log Pattern", "Scope Enforcement").
+- Related: ADR-0000 (why we keep ADRs).
diff --git a/docs/adr/0002-use-effect-for-retry-policies.md b/docs/adr/0002-use-effect-for-retry-policies.md
new file mode 100644
index 000000000..877d02d44
--- /dev/null
+++ b/docs/adr/0002-use-effect-for-retry-policies.md
@@ -0,0 +1,155 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# Use Effect for retry policies
+
+## Context and Problem Statement
+
+openstatus does a lot of I/O against systems it does not control: fetching
+third-party status pages, sending notifications through provider SDKs, and
+sending transactional email. These calls fail transiently — timeouts, rate
+limits, 5xx — and must be retried with backoff rather than failing the whole
+job.
+
+Before Effect, each call site grew its own retry loop. The loops disagreed on
+backoff shape, jitter, attempt counts, and which errors were even worth
+retrying, and most got jitter or the 4xx-vs-5xx distinction subtly wrong.
+
+How should we express retry policies — backoff, jitter, attempt limits,
+timeouts, conditional retry — consistently across the codebase?
+
+## Decision Drivers
+
+- Transient I/O failures need exponential backoff with jitter, not naive loops.
+- A retry policy must support a max attempt count and a timeout per attempt.
+- Some failures must *not* be retried (e.g. HTTP 4xx) — retry must be
+ conditional.
+- One well-tested mechanism beats N hand-rolled loops that each drift.
+- We do **not** want to rewrite the codebase in a new programming paradigm.
+- `effect` is already a dependency (catalog-pinned) in `status-fetcher`,
+ `emails`, and `workflows`.
+
+## Considered Options
+
+- Hand-rolled retry loops at each call site
+- A focused retry library (`p-retry` / `async-retry`)
+- Effect, scoped specifically to retry policies
+- Effect adopted as the general programming model
+
+## Decision Outcome
+
+Chosen option: "Effect, scoped specifically to retry policies".
+
+When code needs a retry policy, wrap the operation in an `Effect` and use
+`Effect.retry` with a `Schedule`. This gives one declarative, composable way to
+express exponential backoff, jitter, attempt limits, per-attempt timeouts, and
+conditional retry — and the adjacent combinators (`Effect.timeoutFail`) compose
+with it for free.
+
+**This ADR scopes Effect to retry/backoff. It is not a decision to adopt Effect
+as openstatus's general programming model.** Reach for Effect when you need a
+retry policy (and the timeout/jitter/scheduling that comes with it); do not
+introduce Effect layers, services, or the `Effect`-everywhere style into code
+that has no retry concern.
+
+### Canonical pattern
+
+The reference implementation is `packages/status-fetcher/src/fetch.ts`:
+
+```ts
+import { Effect, Schedule } from "effect";
+
+const retryPolicy = {
+ schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+ times: 3,
+ while: isRetryable, // e.g. don't retry HTTP 4xx
+};
+
+const result = Effect.tryPromise({ try: () => doIo(), catch: toDomainError })
+ .pipe(Effect.retry(retryPolicy));
+
+await Effect.runPromise(result); // run at the boundary
+```
+
+- Wrap the promise with `Effect.tryPromise({ try, catch })`; map failures to a
+ typed domain error in `catch`.
+- Express the policy as `Schedule.exponential(...)` piped through
+ `Schedule.jittered`; gate retries with `while` so non-retryable errors fail
+ fast.
+- Run the effect at the call boundary with `Effect.runPromise`.
+
+### Existing exception
+
+`packages/services/src/retry.ts` (`withBusyRetry`) is a hand-rolled retry for
+SQLite `SQLITE_BUSY` / `SQLITE_LOCKED` contention. It predates this ADR, covers
+a different concern (DB lock contention inside transactions), and stays as a
+plain loop because the `services` package deliberately minimizes dependencies
+and must remain Edge-safe. It is not a target for migration.
+
+### Consequences
+
+- Good, because backoff, jitter, attempt limits, timeout, and conditional
+ retry are expressed declaratively in one consistent way.
+- Good, because `Effect.tryPromise` + `Effect.runPromise` is a thin, learnable
+ boundary — contributors do not need to learn all of Effect to add a retry.
+- Good, because timeout (`Effect.timeoutFail`) and retry compose cleanly.
+- Bad, because Effect is a large library with a steep learning curve; keeping
+ its use bounded to retry takes review discipline.
+- Bad, because two retry mechanisms coexist (Effect and `withBusyRetry`);
+ contributors must know DB-contention retry is the loop, I/O retry is Effect.
+- Neutral, because it relies on an existing catalog-pinned dependency.
+
+### Confirmation
+
+New retry logic in I/O-heavy code (`workflows`, `status-fetcher`, `emails`, and
+similar) uses `Effect.retry` + `Schedule`. Code review rejects new hand-rolled
+retry loops in those areas, and flags Effect usage that goes beyond
+retry/backoff (layers, services, `Effect`-typed APIs) for explicit discussion.
+
+## Pros and Cons of the Options
+
+### Hand-rolled retry loops at each call site
+
+- Good, because no dependency and nothing new to learn.
+- Bad, because every loop reimplements backoff and drifts from the others.
+- Bad, because jitter and the retryable-vs-fatal distinction are easy to get
+ wrong.
+
+### A focused retry library (`p-retry` / `async-retry`)
+
+- Good, because it is small and does exactly one thing.
+- Neutral, because it would be a new dependency for a problem Effect — already
+ in the tree — already solves.
+- Bad, because timeout and retry would not compose; per-attempt timeout still
+ needs separate code.
+
+### Effect, scoped to retry policies
+
+- Good, because retry, backoff, jitter, scheduling, and timeout are one
+ composable, well-tested toolkit.
+- Good, because it is already a dependency.
+- Bad, because the surrounding library is large; scope has to be enforced.
+
+### Effect as the general programming model
+
+- Good, because it would unify error handling, dependency injection, and
+ concurrency across the codebase.
+- Bad, because it is a very large bet with a steep learning curve for every
+ contributor.
+- Bad, because it would touch code that has no I/O or retry concern, far beyond
+ the problem this ADR addresses.
+
+## More Information
+
+- Reference implementation: `packages/status-fetcher/src/fetch.ts`
+ (exponential + jittered schedule, conditional `while`, composed timeout).
+- Other current usage: `apps/workflows/src/checker/alerting.ts`,
+ `apps/workflows/src/cron/`, `packages/emails/src/client.tsx`.
+- Effect `Schedule` docs: https://effect.website/docs/scheduling/introduction/
+- Revisit if Effect usage starts to sprawl beyond retry, or if a case for
+ adopting it as the general programming model is made — that would be a new
+ ADR superseding the scope set here.
+- Related: ADR-0000 (why we keep ADRs).
diff --git a/docs/adr/0003-shared-ui-comes-from-openstatus-ui.md b/docs/adr/0003-shared-ui-comes-from-openstatus-ui.md
new file mode 100644
index 000000000..9ec4c5d29
--- /dev/null
+++ b/docs/adr/0003-shared-ui-comes-from-openstatus-ui.md
@@ -0,0 +1,125 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# All shared UI comes from `@openstatus/ui`
+
+## Context and Problem Statement
+
+openstatus has three frontend apps — `dashboard`, `status-page`, and `web` —
+that must look and behave like one product. They share a design system built on
+shadcn/ui and Radix: primitives (`button`, `input`, `dialog`, `form`, …),
+openstatus-specific composite blocks (the status-page components), shared hooks,
+and the `cn` class-merge helper.
+
+That shared design system lives in the `@openstatus/ui` package. But each app
+also carries its own `components.json` whose `ui` alias points at a *local*
+`@/components/ui`. Running `npx shadcn add <component>` inside an app therefore
+drops a fresh copy into that app's tree instead of the shared package. Once that
+happens the apps drift: divergent `button` variants, divergent `cn`, duplicated
+and unpinned Radix dependencies, and a public shadcn registry
+(openstatus.dev/r) that no longer matches what the apps actually render.
+
+Where should shared UI components live, and how do we keep apps from forking
+their own copies?
+
+## Decision Drivers
+
+- Three apps plus a public registry must render one consistent design system.
+- A fix to a primitive should reach every app at once.
+- Radix / lucide / recharts versions must be pinned in one place.
+- `@openstatus/ui` is the source of truth for the public shadcn registry; local
+ forks would make the registry lie.
+- Adding a component must not silently create a divergent copy.
+
+## Considered Options
+
+- Each app keeps its own `components/ui` (per-app shadcn install)
+- A single shared `@openstatus/ui` package, consumed as source
+- Publish `@openstatus/ui` as a versioned, pre-built npm package
+
+## Decision Outcome
+
+Chosen option: "A single shared `@openstatus/ui` package, consumed as source".
+
+**All shared UI comes from `@openstatus/ui`, always.** Apps import it directly
+and never keep their own copy of a shared component:
+
+- **shadcn primitives** → `@openstatus/ui/components/ui/<name>`
+- **openstatus blocks** → `@openstatus/ui/components/blocks/<name>`
+- **custom shared components** → `@openstatus/ui/components/custom/<name>`
+- **the `cn` helper and shared utils** → `@openstatus/ui/lib/<name>`
+- **shared hooks** → `@openstatus/ui/hooks/<name>`
+- **global styles** → `@openstatus/ui/globals`
+
+The package has no build step — apps consume the `.tsx` source through the
+`exports` map in `packages/ui/package.json`. Its dependencies are catalog-pinned,
+so every app resolves the same Radix/lucide/recharts versions.
+
+**Adding a new shadcn primitive:** add it under
+`packages/ui/src/components/ui/`, register it in `packages/ui/registry.json`,
+and import it via `@openstatus/ui/...`. Do **not** run `npx shadcn add` against
+an app's `components.json` — that targets the app's local `@/components/ui` and
+forks the component.
+
+**Scope.** This rule covers *shared* UI: primitives, blocks, hooks, and `cn`.
+App-specific feature components (a settings form, a dashboard widget) still live
+in the app under `src/components/`. The rule is: if it is a shadcn primitive or
+is used by more than one app, it must come from `@openstatus/ui` — never a local
+fork.
+
+### Consequences
+
+- Good, because there is one design system and one source of truth; a primitive
+ fix propagates to all three apps and the registry at once.
+- Good, because Radix and other UI dependencies are pinned once via the catalog.
+- Good, because the no-build-step source consumption keeps iteration fast.
+- Bad, because a change to a shared primitive affects all three apps
+ simultaneously and needs corresponding care in review.
+- Bad, because `npx shadcn add` defaults to the app's `components.json`, so
+ contributors must know to add primitives in `packages/ui` instead — a sharp
+ edge this ADR exists to flag.
+- Neutral, because apps must transpile the package source; already configured.
+
+### Confirmation
+
+Code review rejects new files under an app's `src/components/ui/` that
+duplicate a shadcn primitive, and rejects imports of a shadcn primitive from
+anywhere other than `@openstatus/ui`. New primitives appear under
+`packages/ui/src/components/ui/` and in `packages/ui/registry.json`.
+
+## Pros and Cons of the Options
+
+### Each app keeps its own `components/ui`
+
+- Good, because `npx shadcn add` works out of the box with no extra knowledge.
+- Bad, because the three apps drift apart component by component.
+- Bad, because UI dependencies are duplicated and version-skew across apps.
+- Bad, because the public registry no longer reflects the shipped UI.
+
+### A shared `@openstatus/ui` package, consumed as source
+
+- Good, because one source of truth for primitives, blocks, hooks, and `cn`.
+- Good, because no build step — fast iteration, simple debugging.
+- Good, because it is already the source for the public registry.
+- Bad, because `npx shadcn add` has to be pointed at the package deliberately.
+
+### Publish `@openstatus/ui` as a pre-built npm package
+
+- Good, because apps consume a stable, versioned artifact.
+- Bad, because every UI change needs a publish + version bump before apps see
+ it — slow for a monorepo where UI and apps evolve together.
+- Bad, because it adds release tooling for an internal-only consumer.
+
+## More Information
+
+- Package: `packages/ui/` — `src/components/ui` (primitives),
+ `src/components/blocks` (status-page blocks), `src/components/custom`,
+ `src/lib`, `src/hooks`.
+- Registry: `packages/ui/registry.json` + `REGISTRY.md`; built and published to
+ `apps/web/public/r/` and served at https://openstatus.dev/r.
+- The per-app `components.json` files exist for tooling/registry alignment;
+ they are not a license to install primitives locally.
+- Related: ADR-0000 (why we keep ADRs).
diff --git a/docs/adr/0004-go-for-the-probing-tier.md b/docs/adr/0004-go-for-the-probing-tier.md
new file mode 100644
index 000000000..7ae257321
--- /dev/null
+++ b/docs/adr/0004-go-for-the-probing-tier.md
@@ -0,0 +1,119 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# Go for the probing tier
+
+## Context and Problem Statement
+
+openstatus is a synthetic monitoring product: its core job is to probe customer
+endpoints — HTTP, TCP, ICMP, UDP, DNS, SSL — from many geographic locations and
+record how each one responded, down to per-phase timings (DNS, connect, TLS
+handshake, time-to-first-byte, transfer).
+
+That probing service (`apps/checker`) runs as a fleet: ~35 fly.io regions, each
+machine a 512 MB / 2-shared-CPU VM handling up to ~1000 concurrent requests. It
+is also shipped as a Docker image customers run on their own infrastructure for
+private-location monitoring (`apps/private-location`).
+
+The rest of openstatus — dashboard, API server, shared packages — is
+TypeScript. What language should the probing tier be written in?
+
+## Decision Drivers
+
+- A single check fans out into many concurrent, mostly-idle network probes;
+ the runtime must make that concurrency cheap.
+- The fleet runs in ~35 regions on small VMs — low memory footprint and fast
+ cold start matter, and runtime efficiency is a recurring cost.
+- Probing needs low-level network control: per-phase request timing, raw ICMP,
+ custom dialers — not just `fetch`.
+- The probe agent must ship as a small, portable, self-contained artifact that
+ customers can run on their own infrastructure.
+- The contract with the rest of the system is data, not shared code.
+
+## Considered Options
+
+- Go
+- TypeScript / Node (consistent with the rest of the stack)
+- Rust
+
+## Decision Outcome
+
+Chosen option: "Go".
+
+The probing tier — `apps/checker` and `apps/private-location` — is written in
+Go; the rest of openstatus stays TypeScript.
+
+Goroutines make massive probe fan-out cheap without an async-coloring or
+thread-pool model. Go's `net` / `net/http` standard library exposes the
+low-level hooks the product is built on — `httptrace` gives the DNS / connect /
+TLS / TTFB phase timings openstatus reports, and raw sockets cover the
+non-HTTP probe types. A statically linked Go binary deploys as a tiny
+multi-region image and doubles as the self-host artifact with no runtime to
+install.
+
+**The polyglot cost is accepted and deliberately bounded.** Go is confined to
+the edge probing tier. Product and business logic stays in TypeScript
+(`packages/services`, per ADR-0001). The two worlds communicate only through
+explicit data contracts — check results written to Tinybird, jobs delivered
+over HTTP / Cloud Tasks / ConnectRPC (`packages/proto`) — never shared
+in-process code.
+
+### Consequences
+
+- Good, because cheap goroutine concurrency, low memory, and fast cold start
+ fit a ~35-region fleet of small VMs.
+- Good, because the standard library gives direct access to per-phase network
+ timing and non-HTTP protocols.
+- Good, because a single static binary is a portable self-host artifact.
+- Bad, because the repo is polyglot — contributors to the probing tier need Go
+ as well as TypeScript, and CI carries a second toolchain.
+- Bad, because no types or logic are shared across the boundary: assertion
+ evaluation exists twice — `packages/assertions` (TS) and
+ `apps/checker/pkg/assertions` (Go) — and must be kept in sync by hand.
+- Neutral, because cross-boundary contracts (Tinybird schemas, protobuf) are
+ explicit and versioned rather than implicit.
+
+### Confirmation
+
+Go stays scoped to the probing tier. New probing / edge-agent code is Go; new
+product logic is TypeScript in `packages/services`. Any logic duplicated across
+the boundary (assertions, region codes) is called out in review so both copies
+move together.
+
+## Pros and Cons of the Options
+
+### Go
+
+- Good, because goroutines make probe fan-out cheap and simple.
+- Good, because the stdlib exposes per-phase timing and raw network access.
+- Good, because static binaries are small, portable self-host artifacts.
+- Bad, because it makes the repo polyglot.
+
+### TypeScript / Node
+
+- Good, because it would keep the whole codebase in one language with shared
+ types (assertions, region codes, schemas).
+- Bad, because the runtime is heavier per VM and slower to cold-start across a
+ large fleet.
+- Bad, because low-level network timing and non-HTTP probes are awkward and
+ partly unavailable.
+
+### Rust
+
+- Good, because it offers the same efficiency and network control as Go.
+- Bad, because slower iteration and a steeper learning curve for a team whose
+ other backend skills are TypeScript.
+- Neutral, because the concurrency win over Go for this I/O-bound workload is
+ marginal.
+
+## More Information
+
+- Probing tier: `apps/checker` (regional fleet), `apps/private-location`
+ (self-host orchestrator). Deployed on fly.io; see `apps/checker/fly.toml`.
+- Cross-boundary contracts: `packages/tinybird` (results), `packages/proto`
+ (ConnectRPC job delivery).
+- Related: ADR-0001 (business logic lives in the TS services layer),
+ ADR-0005 (check results land in Tinybird).
diff --git a/docs/adr/0005-turso-for-app-data-tinybird-for-time-series.md b/docs/adr/0005-turso-for-app-data-tinybird-for-time-series.md
new file mode 100644
index 000000000..43be3c0c0
--- /dev/null
+++ b/docs/adr/0005-turso-for-app-data-tinybird-for-time-series.md
@@ -0,0 +1,114 @@
+---
+status: "accepted"
+date: 2026-05-22
+decision-makers: openstatus maintainers
+---
+
+# Turso for application data, Tinybird for time-series
+
+## Context and Problem Statement
+
+openstatus stores two very different kinds of data.
+
+**Application data** — workspaces, users, monitors, status pages, incidents,
+notifications, API keys, audit logs. It is relational, low-volume, mutated
+transactionally, and read with joins and workspace-scoped filters.
+
+**Monitoring time-series** — the result of every check, from every region, for
+every monitor, including sub-request phase timings. It is high-volume,
+append-only, and queried as aggregations over time windows: p95 latency and
+uptime over `1h` / `1d` / `7d` / `45d`, grouped by region.
+
+These are different workloads. What should store each one?
+
+## Decision Drivers
+
+- Application data needs transactional integrity, foreign keys, joins, and the
+ fail-closed audit-log invariant (ADR-0001).
+- Monitoring data is a firehose: a large fleet of probes (ADR-0004) writes
+ results continuously, and a relational row store would buckle under it.
+- Dashboard queries over monitoring data are time-window aggregations — a
+ columnar / OLAP shape, not a row-store shape.
+- The probing fleet needs a write endpoint it can hit directly, decoupled from
+ the application database.
+- The dashboard runs on the Edge and needs low-latency reads of application
+ config.
+- We do not want to operate an analytics database ourselves.
+
+## Considered Options
+
+- A single relational database for everything
+- Turso (libSQL) for application data + Tinybird for time-series
+- Turso for application data + a self-hosted analytics DB (ClickHouse /
+ TimescaleDB)
+
+## Decision Outcome
+
+Chosen option: "Turso (libSQL) for application data + Tinybird for time-series".
+
+**Turso (libSQL — SQLite)** holds the relational application schema, accessed
+through Drizzle ORM in `packages/db`. It gives transactional, workspace-scoped
+writes, foreign keys, the audit-log invariant, and fast Edge-friendly reads.
+
+**Tinybird (ClickHouse-backed)** ingests and serves the monitoring time-series.
+The probing fleet writes check results straight to Tinybird; the dashboard and
+API read aggregated metrics from Tinybird pipes via `packages/tinybird`. Its
+managed pipes and materializations mean no analytics database to operate.
+
+The two stores are linked **only by id** — a Tinybird row carries `monitorId` /
+`workspaceId`, but there are no cross-store transactions and no joins across
+the boundary. Each store runs the workload it is built for.
+
+### Consequences
+
+- Good, because each workload runs on a store designed for it: transactional
+ integrity on one side, fast time-window aggregation on the other.
+- Good, because the probing fleet writes to a managed ingestion endpoint — a
+ check-volume spike cannot degrade the dashboard's application database.
+- Good, because Tinybird's managed pipes remove the need to run an analytics DB.
+- Bad, because there is no referential integrity across the boundary: deleting
+ a monitor leaves orphaned time-series; cross-store consistency is eventual
+ and by convention.
+- Bad, because there are two clients and two sets of schemas (Drizzle models
+ vs. zod-bird pipe schemas) to keep aligned.
+- Bad, because a managed third party is on the critical path for metrics;
+ self-hosters must provide Tinybird or an equivalent.
+
+### Confirmation
+
+Relational / configuration entities get a Drizzle schema under
+`packages/db/src/schema/`. Monitoring events and their aggregations go through
+`packages/tinybird`. A new high-volume, append-only event stream defaults to
+Tinybird, not a new Turso table; a new configuration entity defaults to Turso.
+
+## Pros and Cons of the Options
+
+### A single relational database for everything
+
+- Good, because one store, one client, one mental model, and joins everywhere.
+- Bad, because a row-oriented SQLite database cannot absorb continuous
+ check-result volume from a large probing fleet.
+- Bad, because time-window aggregations over that volume would be slow and
+ would contend with transactional application traffic.
+
+### Turso for application data + Tinybird for time-series
+
+- Good, because each store matches its workload.
+- Good, because ingestion is decoupled and the analytics tier is managed.
+- Bad, because no cross-store integrity and two schema surfaces to maintain.
+
+### Turso + a self-hosted analytics DB
+
+- Good, because it keeps the analytics data fully under our control.
+- Good, because it removes the third-party dependency for self-hosters.
+- Bad, because operating ClickHouse/TimescaleDB — ingestion, materialized
+ views, scaling, backups — is a significant ongoing cost.
+
+## More Information
+
+- Application data: `packages/db` (Drizzle + `@libsql/client`); schema under
+ `packages/db/src/schema/`.
+- Time-series: `packages/tinybird` (built on `@chronark/zod-bird`); the
+ probing fleet writes results here directly.
+- Related: ADR-0001 (the audit-log invariant lives in Turso), ADR-0004 (the
+ probing fleet is the primary writer to Tinybird).
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 000000000..158fee119
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,44 @@
+# Architecture Decision Records
+
+This directory holds the architecturally significant decisions made on
+openstatus, in [MADR](https://adr.github.io/madr/) format.
+
+An ADR captures *why* a decision was made, what alternatives were weighed, and
+what trade-offs were accepted. `CLAUDE.md` documents the conventions in force
+today; ADRs explain how those conventions came to be.
+
+## Index
+
+| ADR | Title | Status |
+| --- | --- | --- |
+| [0000](0000-use-markdown-any-decision-records.md) | Use Markdown Any Decision Records (MADR) | accepted |
+| [0001](0001-business-logic-lives-in-the-services-layer.md) | Workspace business logic lives in a framework-agnostic services layer | accepted |
+| [0002](0002-use-effect-for-retry-policies.md) | Use Effect for retry policies | accepted |
+| [0003](0003-shared-ui-comes-from-openstatus-ui.md) | All shared UI comes from `@openstatus/ui` | accepted |
+| [0004](0004-go-for-the-probing-tier.md) | Go for the probing tier | accepted |
+| [0005](0005-turso-for-app-data-tinybird-for-time-series.md) | Turso for application data, Tinybird for time-series | accepted |
+
+## When to write an ADR
+
+Write one when a decision is hard to reverse, cross-cutting, or non-obvious —
+for example:
+
+- adopting or dropping a framework, library, or runtime;
+- a repo-wide pattern every contributor must follow;
+- a data-model or API-contract decision that is expensive to change;
+- choosing one approach over a reasonable alternative someone would ask about.
+
+Skip it for routine, local, or easily reversible changes.
+
+## How to add one
+
+1. Copy `template.md` to `NNNN-kebab-case-title.md`, where `NNNN` is the next
+ zero-padded number.
+2. Fill it in. Keep it short — drivers, options, outcome, consequences.
+3. Add a row to the index above.
+4. Open it in the same PR as (or just before) the change it describes.
+
+## Changing a decision
+
+ADRs are immutable once accepted. To change a decision, write a new ADR and set
+the old one's `status` to `superseded by ADR-NNNN`.
diff --git a/docs/adr/template.md b/docs/adr/template.md
new file mode 100644
index 000000000..92c860e16
--- /dev/null
+++ b/docs/adr/template.md
@@ -0,0 +1,58 @@
+---
+# Optional metadata. Remove any element you don't need.
+status: "{proposed | rejected | accepted | deprecated | superseded by ADR-NNNN}"
+date: { YYYY-MM-DD when the decision was last updated }
+decision-makers: { everyone involved in the decision }
+consulted: { subject-matter experts consulted, with two-way communication }
+informed: { people kept up to date, with one-way communication }
+---
+
+# {short title, representative of the problem and the chosen solution}
+
+## Context and Problem Statement
+
+{Two or three sentences, or a short story, describing the context and the
+problem. Framing the problem as a question often helps. Link issues/PRs.}
+
+## Decision Drivers
+
+- {driver 1 — a force, a concern, a constraint}
+- {driver 2}
+
+## Considered Options
+
+- {option 1}
+- {option 2}
+- {option 3}
+
+## Decision Outcome
+
+Chosen option: "{option N}", because {justification — meets a must-have driver,
+resolves a key force, or comes out best in the comparison below}.
+
+### Consequences
+
+- Good, because {positive consequence}
+- Bad, because {negative consequence / accepted trade-off}
+
+### Confirmation
+
+{How compliance with this ADR is checked — a review, a test, a lint rule,
+a sign-off.}
+
+## Pros and Cons of the Options
+
+### {option 1}
+
+- Good, because {argument}
+- Neutral, because {argument}
+- Bad, because {argument}
+
+### {option 2}
+
+- Good, because {argument}
+- Bad, because {argument}
+
+## More Information
+
+{Extra evidence, team agreement, when to revisit, links to related ADRs.}