Skip to content
oto
Menu
Overview
IntroductionConceptsArchitectureContributingReleasing
Design
oto — System Design ProposalDomain Research: Prometheus Alertmanager + Slackoto — Red-Team Memooto — SCOPE BOUNDARY (the doctrine)oto — BINDING SPECIFICATION v1
ADRs
0001 — PostgreSQL is the sole datastore; River is the job queue0002 — `internal/<domain>/{api,service,repository,domain}` with three model sets0003 — Alert, AlertOccurrence and AlertEvent are three distinct entities0004 — oto owns alert identity; Alertmanager's fingerprint is recomputed, not trusted0005 — A durable group key, and the AlertGroup generation owns the Slack thread0006 — The Alertmanager API v2 reconciler is mandatory, not optional0007 — Webhook response contract: 202 or 503. Never 4xx, never 429.0008 — Slack: `chat.update` in place is primary; threads are secondary; one colour attachment0009 — Rule definitions are snapshotted and versioned at fire time0010 — Server-Sent Events with durable resume, not WebSocket0011 — Validation is seven layers with two opposite trust models0012 — Pastel product chrome, saturated colour reserved exclusively for state0013 — oto is alert-first: the Flight Recorder Test defines the scope boundary0014 — Postgres is the only store; no TSDB or column store in v10015 — No stream processor; River in Postgres is the pipeline0016 — Cluster context arrives via MCP, on demand; never the Kubernetes event firehose0017 — Alertmanager-style matchers, not CEL; and a filter AST that keeps the door open0018 — Slack distribution: a customer-built internal app, credentials in config0019 — MIT licence0020 — Broadcast the transitions that must be seen0021 — Correctness and testing strategy0022 — Length-prefixed identity pre-images0023 — Terminal thread states are decided first, and the send is three phases0024 — Retention defaults, what each boundary destroys, and cold storage0025 — The alert list resolves rule snapshots in a batch, not per row0026 — `refire_grace` and the flap thresholds, derived from a real rule corpus0027 — Delivery drills: a synthetic alert through the real pipeline, and the mark that keeps it out of the numbers0028 — Non-urgency motion: one-shot events, honest activity loops, and nothing else0029 — Type and radius scales, read off the product rather than drawn for it0030 — Tier A repainted as Washi & Ink / Konshi Sutra; accent moves to beni0031 — Sharp corners and higher-contrast grid lines within Washi & Ink; colours unchanged0032 — Dark-theme accent moves from beni to plum-blossom blue-and-white; light untouched0033 — The alert filters are a toolbar above the table, not a panel in the rail0034 — Notifications is a destination, and the record it keeps is readable0035 — Decorative ink as a masked wash: one primitive, four motifs, and the placements it is refused0036 — AlertOccurrence becomes AlertCase, and `case` is argued against FR-1 by name0037 — A Wording is Liquid, and the structure around it stays oto's0038 — The group key is derived from the alert's own labels0039 — Group close stays activity-driven0040 — A Case is `open` or `closed`, and it is never reopened0041 — The Alert/Case allocation, and the one rule that decides it0042 — Storm damping is removed, because the defence was built before its object0043 — The Slack action row renders five elements, and the fifth is the snooze pair0044 — A count condition is a silence the operator asked for, and `below_threshold` is how oto says so0045 — A Case is a conversation, and one Slack thread per alert is the accepted cost0046 — Corners round again: ADR 0031's radius override is reversed0047 — A channel answers to a connection, and Slack gets two scopes back0048 — A Wording is spelled by its channel, and the marks in between are oto's0049 — A Wording is selected by its own clause, not by a route0050 — A NotificationTemplate is one whole message, and its policy says which one0051 — A `raw` template owns the whole message, and a template may carry its replies0052 — An Incident is drawn over Cases, and its response is handed off0053 — An Investigator reads, proposes, and never decides delivery0054 — A Remedy earns the write path0055 — An incident-tool integration is data or a bridge, never code inside oto0056 — A Case the upstream stopped speaking about expires, and says why
Setup
Configuration referenceReaching an incident tool: the envelope, a mapping, or a bridgeInvestigatorsRemediesConnecting oto to SlackThe live Slack verification runTuning otoConnecting oto to VictoriaMetrics (vmalert)The generic webhook and `oto.notification.v1`
Runbooks
oto runbooksAlert search — optional partial/substring matching on alert namesoto_clock_skew_secondsoto_delivery_claim_lost_totaloto_ingest_accepted_totaloto_ingest_alerts_totaloto_ingest_duplicate_totaloto_ingest_duration_secondsoto_ingest_fingerprint_mismatch_totaloto_ingest_process_duration_secondsoto_ingest_rejected_totaloto_ingest_shed_totaloto_job_duration_secondsoto_job_queue_depthoto_jobs_dead_totaloto_jobs_enqueued_totaloto_jobs_failed_totaloto_jobs_panics_totaloto_jobs_snoozed_totaloto_jobs_started_totaloto_jobs_succeeded_totaloto_jobs_unknown_version_totaloto_render_invalid_totaloto_slack_unknown_action_totaloto_stream_connectionsoto_stream_events_coalesced_totaloto_stream_events_dropped_totaloto_stream_events_fetched_totaloto_stream_events_published_totaloto_stream_fetch_errors_totaloto_stream_listener_reconnects_totaloto_stream_notify_malformed_totaloto_stream_notify_received_totaloto_stream_poll_recovered_totaloto_stream_resync_totaloto_thread_gap_recovered_totaloto_thread_head_wait_secondsoto_thread_order_decisions_total

0031 — Sharp corners and higher-contrast grid lines within Washi & Ink; colours unchanged

Status: Accepted · 2026-08-16 · SUPERSEDED IN PART by 0046 (2026-08-21), which reverses this ADR’s radius decision and returns all three steps to ADR 0029’s values. The border-contrast decision below is not reversed and still stands · amends the radius values of ADR 0029 (not the tier structure) and the --oto-border/--oto-border-strong values of ADR 0030 (not the rest of the palette)

Context

Section titled “Context”

The owner asked for an Enterprise Technical / Bloomberg Terminal aesthetic — or a Sharp Bento / Swiss Modernist hybrid — for a dashboard whose whole surface is dense tables, rows, filters and group-by controls. A first pass (since reverted) took that literally: a generic cool-slate palette with a monochrome ink accent, replacing Washi & Ink entirely. The owner corrected that: keep Washi & Ink’s colours — the warm cream/sumi-ink light theme, the indigo Konshi Sutra dark theme, the beni crimson-pink accent — and get the Bloomberg/Swiss Modernist read from geometry, not from a new palette. That is what this ADR does.

Two structural properties carry that aesthetic, independent of hue: sharp corners (the rounded, soft-edged look is the opposite of a terminal grid) and crisp, legible grid lines (a dense table needs borders that read at a glance, not hairlines that all but disappear). Neither requires touching --oto-bg, --oto-surface, --oto-text, or --oto-accent — all four, in both themes, are byte-identical to what ADR 0030 shipped.

Decision

Section titled “Decision”

1. All three radius steps go to 0px. --oto-radius-chip, --oto-radius-control, and --oto-radius-surface — 3px/4px/6px since ADR 0029 — all render 0px. The three tiers themselves are unchanged: a badge still reaches for rounded-chip, a button for rounded-control, a dialog for rounded-surface, and the reason ADR 0029 gave for keeping three distinct names (inline vs operable vs surface-holding-controls) is not in dispute — only the value each name carries changed. This is an explicit override of ADR 0029’s “derived from the census, not designed” methodology: 0px was never one of the 342 literals that census was built from, and this ADR does not pretend otherwise. rounded-full and rounded-none are unaffected, as they were always shapes rather than scale steps.

2. --oto-border and --oto-border-strong get darker (light) / brighter (dark), same hue. Both move within their existing hue family — the warm khaki/tan of Washi & Ink’s light border (~42° hue) and the indigo of Konshi Sutra’s dark border (~222–226° hue) are unchanged; only lightness and saturation shift, toward more contrast:

Token Theme Was Now vs --oto-surface
--oto-border light #E1D2AF #D2B879 1.9:1 (was ~1.5:1)
--oto-border-strong light #C4AE7E #A3833E 3.5:1 (was 2.1:1)
--oto-border dark #303C58 #435889 2.1:1 (was ~1.4:1)
--oto-border-strong dark #46527A #6476AF 3.3:1 (was un-tabulated)

--oto-border-strong now clears 3:1 in both themes — genuinely “reads as a line” rather than a decorative wash — while --oto-border stays a hairline, just a less washed-out one. --oto-chart-grid moves with --oto-border, as it always has (§M.4/§M.5).

Both tokens remain decorative per §M.4’s note: neither is the sole carrier of meaning, and any border that does carry meaning is a Tier-B -border/-solid token, all of which already clear 3:1 and are untouched here.

3. Everything else is untouched. --oto-bg, --oto-surface, --oto-surface-raised, --oto-surface-sunken, --oto-text, --oto-text-muted, --oto-text-subtle, --oto-accent (and its -hover/-fill/-border/-focus siblings), every Tier-B state token, and the type/spacing scales are exactly what ADR 0030 and ADR 0029 shipped.

Consequences

Section titled “Consequences”
  • Every rendered corner in the product goes flush; nothing rounds except rounded-full shapes (avatars, status dots) and anywhere a component explicitly opts into rounded-none (already a no-op today).
  • Table grids, panel dividers and input outlines read noticeably more defined, especially --oto-border-strong, which now clears the same 3:1 bar Tier-B borders already meet.
  • §M.4/§M.5’s measured-contrast tables gain one new row each (--oto-border-strong vs --oto-surface, both themes) and contrast.test.ts/tokens.test.ts were run green with the new values before this landed.
  • §M.8’s census table is retained as history — it still correctly explains why there are three radius tiers and where chip and control split — with a note that the values those tiers hold were overridden, not re-derived, by this ADR.
  • The product UI and DESIGN.md’s marketing brand stay visually related (same washi/konshi hues, same beni accent) even though the product’s corners and grid weight now read more technical than the marketing site’s — that divergence is intentional: a dashboard’s tables have a density and precision job the marketing site does not.

Alternatives rejected

Section titled “Alternatives rejected”
  • A generic slate/monochrome repaint (the first pass, reverted). Rejected per the owner’s direction: it solved the geometry problem by discarding the brand, when the geometry problem (sharp corners, crisp grid) doesn’t require touching colour at all.
  • A smaller radius (e.g. 2px) instead of 0px. Considered, but a partial round still reads as “rounded, just less so” rather than as the sharp, drafting-table geometry the owner asked for; 0px is the unambiguous version of the same request.
  • Leave --oto-border/--oto-border-strong as-is and rely on radius alone for the technical read. Rejected: a dense table’s legibility depends on its grid lines being visible at a glance, and the previous border-strong (2.1:1) was tuned as a subtle decorative wash, not a working grid line — sharp corners alone would not have delivered “Bloomberg Terminal” density.