Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.}