Decision register

Question to resolve

Where do observation-time history and Battery Assurance evidence live, and which retention window applies to the local buffer, current state, operational history, and the Assurance record?

Dependencies. Replay, incident recovery, and the Broadwater outage need a durable accept before the collector retires rows. The prototype’s 7-day screen and any “about 30 days” host sketch are not that decision.

Next evidence. A one-page retention proposal with those four windows and a sample volume at the Broadwater cadence. No vendor price is required to choose a shape.

Relational record plus an observation log Recommendation

Fits when. A Broadwater-scale pilot grows into a fleet, and sites, collectors, UPS assets, battery installations, incidents, and findings need stable identities.

Consequence. Current state stays a small latest-reading table. Raw observations can use a longer or shorter clock than incidents. You operate one database family, with a migration path if the pilot starts on a single node. Downsampling must keep unknown time as unknown.

Single-file embedded store Open

Fits when. The first build serves one site, one operator, and a backup story that is “copy the file.”

Consequence. Enough for a Broadwater-shaped pilot if retention stays modest. Moving later to a server engine is a migration project. Concurrent dashboard writes and collector ingest share one process, so backup and upgrade need a quiet window.

Time-series engine for readings, relational store for the rest Open

Fits when. Range queries and rollups dominate, and incidents plus Assurance stay in a system of record.

Consequence. Two systems to run. A metrics database filled by scraping current gauges is a different path: scrape does not replay an outage gap. See the replay sequence and monitoring choices.

Object archive of raw batches, plus a query index Open

Fits when. You want the original upload batches kept for audit longer than the dashboard’s hot window.

Consequence. Replay and “what did the collector send?” are straightforward. Day-to-day screens need the index. Partial batch failure and local overflow still have to appear as gaps. This option does not choose a vendor, and it does not settle Cloudflare or any other edge (d4).

Question to resolve

How does an operator prove identity, without moving collector credentials or UPS secrets off their current boundaries?

Dependencies. Incident acknowledgement and Assurance resolution need an actor. Scrape-only sites might not. Collector enroll and revoke stay as they are either way.

Next evidence. Name the identity provider for the pilot, or explicitly accept Cloudflare Access with GitHub for that pilot only. Session length and how the CLI logs in are part of the same decision.

Cloudflare Access with GitHub Proposed

Fits when. Operators should have no password inside MainsKeeper, and Cloudflare in front of the dashboard is acceptable.

Consequence. Dashboard sign-in depends on GitHub and Cloudflare Access. Collector ingest can still use the device credential on another path. Choosing this UI concept does not by itself place telemetry, storage, or DNS on Cloudflare (d4 stays open).

OIDC against an identity provider you already run Recommendation

Fits when. The Broadwater pilot should not depend on Cloudflare, and people already sign in somewhere else.

Consequence. Same “no local passwords” outcome. You still decide session length, how the CLI proves an operator, and what the dashboard does while the identity provider is unreachable. No vendor is implied until one is named in review.

Application-local passwords

Fits when. No identity provider is available at all.

Consequence. Conflicts with the explored UI, which has no local passwords. Adds storage, reset, and shared-account problems the design avoided. Recorded here so review can reject it on purpose.

Network restriction only Open

Fits when. A standalone Prometheus scrape on a trusted network needs a boundary, and that path has no dashboard accounts. Scrape authentication itself is still open on the metrics interface.

Consequence. An access list cannot record who acknowledged an incident or who resolved an Assurance finding. It is a poor fit for the centralized product path, and it does not replace the collector credential.

Question to resolve

Which sites, if any, stop at current-state scrape, and which sites get enrollment, replayed history, alerts, and Assurance?

Next evidence. Say whether the Broadwater pilot must reconstruct the outage walkthrough after a WAN loss. If it must, scrape-only is not sufficient for that site.

Standalone Prometheus and Grafana Proposed

Fits when. An existing metrics stack already has an audience, and the job is current gauges.

Consequence. Outage gaps stay gaps. There is no enrollment UX, no Assurance finding, and no replay. Local buffering is still worth doing if you later want history. Depends on a scrape authentication choice (metrics interface).

Centralized MainsKeeper platform Accepted as product direction

Fits when. Fleet view, history, alerts, and Assurance are the product being evaluated.

Consequence. You still owe storage (d2), operator login (d3), and a runtime (d1). Accepting the product direction does not accept Cloudflare, a database, or a deploy topology.

Hybrid, per site Recommendation

Fits when. Broadwater should prove replay and alerts, while another site keeps today’s Grafana boards.

Consequence. Collectors stay the same kind of agent. Operators must be able to tell a scraped gauge from a replayed history. Figure 14 draws both paths and leaves the open boxes unconnected.

Question to resolve

Which boards and which UPS models may be described as supported, and at what cadence their flash actually holds the unacknowledged span?

Next evidence. A measured flash budget, a retention run at the chosen interval, and a USB-HID read against each candidate UPS. No full NUT stack is in scope for this probe.

Defer claims until that list exists Recommendation

Fits when. The Broadwater pilot is a Pi, which it is, and Shop’s probe must not be marketed from fixture numbers.

Consequence. Platform targets still include a validated ESP32. The pilot checklist does not gate on it. Fixture figures stay labelled illustrative.

Ship an image with the illustrative label Open

Fits when. Someone needs a hardware spike before the list exists.

Consequence. Every screen and diagram that shows a sample retention number has to keep the pending label. A spike is not a compatibility promise.

Drop ESP32 from the first release Open

Fits when. No board is available to measure.

Consequence. Equipment-only sites then need a Pi or another host. The product target does not disappear just because the first release skips it. Do not redraw Chapter 2 as if the pattern was rejected.

Question to resolve

What must pass before Broadwater is considered to have exercised the design, and what is explicitly not settled by that pass?

Next evidence. Walk the outage story and the 21 checks against a build. Checkbox marks in this guide are review notes in one browser. They are not that evidence.

Pi witness and two UPS sources first Recommendation

Fits when. You want enroll, mixed USB and network reads, revoke, replay, and one battery replacement before more platforms.

Consequence. macOS, Windows, Fedora, and ESP32 remain targets. Their order is not decided here. Storage, auth, and edge stay open even if every box is checked.

All five platforms before any site is called done Open

Fits when. A release is not allowed to omit a target that the design already names.

Consequence. Broadwater cannot finish while ESP32 validation is open. That couples a site pilot to d7 and will wait on hardware that this site shape does not use.

Lab fixtures only Open

Fits when. No site is available and the goal is contract tests.

Consequence. You can prove replay rules with synthetic clocks. You will not learn whether the Pi, the UPS cables, or the operator’s reading of contact-lost match the guide. Do not report fixture output as Broadwater measurements.