PRD

RECHAJ — MocX Smart Technologies Inc.

Tricycle Hardware — Battery PM Dashboard (v0)

Product Requirements Document — Engineering


Status	v1.2 — draft. Specified ahead of the prototype from the `pm-battery` placeholder catalog entry, informed by the validated v0 mockup (KPI strip, fleet composition, fault queue, card-based fleet grid). Revised in v1.1 to split the single screen into two views — Fleet and Issues/Faults — per §5. Revised in v1.2 once the interactive prototype was built: the Fleet listing is a table (not a card grid — no such atom exists elsewhere in the canon), and filters are page-local (not shared across the view switch) — matching every other multi-page Atlas persona.
Date	August 2026
Prepared by	Product Team (Tricycle Hardware)
Owners	Battery PM (TBD) · Tricycle Hardware
Scope	Atlas (web) — Battery PM persona only. The VP, Battery is a separate, higher-altitude persona covered by its own later PRD — the two must not be conflated (see §3, §9).
Source of truth	This PRD for the dashboard. The Battery API suite (endpoint contracts defined separately, outside this repo at time of writing) is the source of truth for battery identity and battery events this dashboard consumes — see §4.
Classification	CONFIDENTIAL

1. Executive Summary

Rechaj runs a battery-as-a-service model for electric tricycles: ~1,500 batteries across four swap stations. The Battery API suite is the single source of truth for battery identity and battery events, read from and written to by every app that touches a battery — production floor, maintenance, swap, field support, revenue assurance, finance, God-mode/VCU, and energy web/CCU.

This PRD scopes one consumer of that API: the Battery PM’s dashboard. The Battery PM is a hands-on operational owner — responsible for fleet health, fault response, state-of-health (SoH) monitoring, and day-to-day battery-to-tricycle ratio decisions. At any moment they need to answer: how many batteries are in each state, which ones need attention right now, and what happened to a specific battery over time. The product direction is command-and-control, not reporting — dense, near-real-time, built for fast scanning and drill-down on demand, like an ops room screen, not a static dashboard.

The dashboard is two views, not one screen (§5): a Fleet view carrying the command-and-control center (KPI strip, fleet composition, fleet table), and an Issues/Faults view scoped to everything fault- and issue-related — the fault queue plus SLA/aging visibility into batteries that have been out of commission too long.

A second persona, the VP, Battery, gets a separate PRD later, scoped to fleet-wide financial and strategic reporting. That is explicitly out of scope here — this PRD stays at the operational altitude the Battery PM works at.

2. Ecosystem — the Battery API suite

This dashboard is one of several apps consuming the same Battery API:

App	Relationship to battery data
Battery PM dashboard (this PRD)	Fleet-wide operational read + triage-level write (fault acknowledgment, assignment, notes)
Production floor	Writes onboarding/assembly events
Maintenance	Writes service/repair events; executes the physical response to a fault this dashboard surfaces
Swap	Writes swap events (mount/unmount, station, rider)
Field support	Writes field-incident events
Revenue assurance	Reads battery/rider association for billing integrity
Finance	Reads asset-value and write-off events
God-mode / VCU	Reads live telemetry, including the continuous SoH/SoC feed
Energy web / CCU	Writes charge-cycle events

Every one of these is a peer consumer, not a subordinate of this dashboard. The Battery PM dashboard does not own onboarding, maintenance dispatch, or swap logistics — it surfaces the fault and the history, and hands the physical action to the app that owns it. Where this repo already documents adjacent work — the Battery Identity & Lifecycle PRD (products/rechaj-inventory-app/docs/TH-Battery Identity & Lifecycle PRD-210526-155643.pdf) and the built Battery Identity Admin flow (products/atlas/flows/battery-identity-admin/) — their exact relationship to the new Battery API suite (superseded by it, or one of its consumer apps) is not yet resolved; see §8 Open Questions. This PRD does not assume either answer.

3. Persona — Battery PM


Role	Battery PM (Tricycle Hardware)
Platform	Atlas web (desktop-first, 1440px)
Goals	Keep the fleet healthy and available; catch and respond to faults fast; monitor SoH trend and drift before it becomes a failure; make the battery-to-tricycle ratio call per station
Entry point	Login — the Fleet view is the default landing screen, always current
Exit point	A fault is acknowledged and routed to the owning app (maintenance, swap), or a ratio/SoH observation becomes a decision made outside this screen
Explicitly not this persona	Fleet-wide financial reporting, revenue/cost analysis, strategic capacity planning — that’s the VP, Battery (separate future PRD)

North star — Fleet Utilization: the share of the fleet actively in service (not faulted, not quarantined, not out for maintenance). Supporting KPIs: fleet size, active-fault count, and SoH drift (see §6). Exact target thresholds are open — see §8.

4. Data Model (consumed, not owned, here)

The Battery API models a battery as an object with attached event-objects — this dashboard reads that model; it does not define it.

Identity properties on the battery object: Battery ID, Serial Number, BMS ID.
Events: every event carries a full audit trail — what happened, who logged it, when. Event types include (non-exhaustive, per §2’s consumer list) onboarding, swap, charge cycle, fault, service/repair, and retirement.
State of health (SoH) is two-tier, and the two tiers must never be merged into one number:
- Continuous BMS estimate — a live, frequently-updated estimate read from the battery’s BMS.
- Quarterly audit-grade pack-aging value — a periodic, higher-confidence measurement.
- Anywhere this dashboard shows SoH, it shows both, labeled distinctly. “SoH drift” (the KPI in §6) is the divergence between the two — a growing drift is itself a signal, and collapsing it into a single blended number would hide exactly that.

5. Dashboard Structure

Two views, reachable from persistent primary navigation (the sidebar), not one screen. Fleet-state command-and-control and fault/issue triage are different rhythms of work — the fleet table needs the whole screen at ~1,500-battery scale, and issue triage needs dedicated room for the SLA/aging aggregates below — so splitting them into their own views keeps each one scannable instead of forcing both into one crowded page. Filters (station, status, date range) are page-local — each view keeps its own filter state, not shared across the switch — see FR-6.

5.1 Fleet view (default landing)

The command-and-control center, built around the three blocks already validated in the v0 mockup:

Block	Purpose
KPI strip	Fleet size, utilization, SoH drift, active-fault count — the four numbers the PM should be able to read in one glance on login
Fleet composition	Breakdown of the ~1,500-battery fleet by status (in-service, spare/idle, faulted, in maintenance, retired) and by station (4 stations), plus the current battery-to-tricycle ratio per station against target
Fleet table + battery detail	A searchable/filterable table across the fleet (filterable/searchable by Battery ID, Serial Number, BMS ID, station, or status — required at ~1,500-battery scale); clicking a row opens that battery’s full event history: event type, time, SoH (both tiers, per §4), SoC, and who logged it

5.2 Issues/Faults view

Everything fault- and issue-related, separated out of the Fleet view so it gets room to be more than a single queue:

Block	Purpose
Fault queue	Every active fault, with severity and a suggested action; the PM’s primary fast-scan surface — ordered so the most urgent items are always on top
SLA/aging breakdown	Batteries currently out of commission (faulted, quarantined, or in maintenance — see §8 open question on exact statuses) surfaced by elapsed time out of service, with any battery past the SLA threshold flagged as a breach — this is the view that answers “what’s been sitting broken too long,” which the fault queue alone (ordered by severity, not age) doesn’t surface

Further issue-oriented aggregates this view could carry — e.g. fault recurrence per battery, longest-open unacknowledged faults, fault distribution by station or type — are open; see §8.

The exact canonical Atlas components (KPI card, table, grid, drawer, tabs/nav for the view switch) are chosen from PATTERNS.md when the flow itself is built — this PRD specifies the views, not the markup.

6. Functional Requirements

FR-1 The Fleet view’s KPI strip shows fleet size, utilization (% in-service), SoH drift, and active-fault count, refreshed on the dashboard’s read cadence (§7).
FR-2 The Fleet view’s fleet composition breaks the fleet down by status and by station, and shows the current battery-to-tricycle ratio per station next to its target.
FR-3 The Issues/Faults view’s fault queue lists every active fault with a severity tier and a suggested action; the PM can acknowledge and assign a fault directly from this queue — logged as an audit-tracked event via the Battery API (who/what/when).
FR-4 The Fleet view’s fleet table supports search/filter by every identity property (Battery ID, Serial Number, BMS ID) plus station and status, at full fleet scale (~1,500 batteries) without pagination that breaks fast scanning.
FR-5 Clicking any battery opens its full event history: every event in chronological order with type, timestamp, SoH (both tiers, never merged), SoC, and the audit who/what/when.
FR-6 Filters (station, status, date range) are page-local: each view’s filters apply consistently across every block within that view, but are not shared or persisted when the PM switches between the Fleet and Issues/Faults views — matching every other multi-page Atlas persona.
FR-7 In scope for direct write: fault acknowledgment, assignment, and notes — the triage-level actions a PM makes in the moment. Out of scope: any action owned by another consumer app in §2 (onboarding, physical repair, swap execution, financial write-off) — this dashboard surfaces and hands off, it does not re-implement those actions.
FR-8 No financial, revenue, or fleet-wide strategic reporting appears on this dashboard — that is the VP, Battery’s dashboard (§9).
FR-9 The Issues/Faults view’s SLA/aging breakdown lists every battery currently out of commission, sorted by elapsed time out of service, and flags any battery whose time out of commission exceeds the SLA threshold (§8) as a breach.

7. Non-Functional Requirements

NFR-1 (real-time) This is a command-and-control surface, not a periodic report — the read cadence should be near-real-time (exact polling/push contract is an implementation detail for the Battery API integration, not fixed by this PRD).
NFR-2 (scale) Every view must perform at the full ~1,500-battery fleet scale — the fleet table in particular needs client-side filtering fast enough to support “fast scanning,” not a slow paginated table.
NFR-3 (data integrity) The two SoH tiers (§4) are never combined into a single value anywhere in this UI, including in exports or tooltips.
NFR-4 (platform) Atlas web, 1440px, canonical components per PATTERNS.md — finalized when the flow is built.

8. Open Questions

Relationship to existing repo artifacts. Does the new Battery API suite supersede the Battery Identity & Lifecycle PRD’s identity model and the built Battery Identity Admin flow, or does Identity Admin become one of §2’s consumer apps? This needs an answer before the flow is built, since it determines whether this dashboard’s fault-hand-off (FR-7) routes there.
Utilization and ratio targets. What’s the target Fleet Utilization %, and is the battery-to-tricycle ratio target uniform across the four stations or set per station based on swap cadence?
Fault severity taxonomy and suggested-action logic. Where do severity tiers and suggested actions come from — fixed rules, a maintenance-team-owned mapping, or something the Battery PM configures?
SoH drift alert threshold. What divergence between the continuous BMS estimate and the quarterly audit value should surface as a KPI-level alert versus quietly tracked?
Read cadence. Does the Battery API support push/webhook updates for near-real-time refresh, or is this dashboard polling — and at what interval?
SLA/aging definition (§5.2, FR-9). What elapsed-time threshold counts as an SLA breach for a battery out of commission, and which statuses count toward it — faulted only, or also quarantined and in-maintenance? Is the threshold uniform fleet-wide or set per station/fault type? The prototype uses a 5-day placeholder threshold applied to Quarantined/Maintenance batteries fleet-wide until this is answered.
Further Issues/Faults aggregates. Beyond the fault queue and SLA/aging breakdown, what other issue-oriented views belong on this screen — fault recurrence per battery, longest-open unacknowledged faults, distribution by station/type? Not yet specified; candidates listed in §5.2.

9. Success Criteria

The Battery PM can answer “what’s happening to the fleet right now” from the Fleet view’s KPI strip alone, without opening any other tool or sheet.
New faults are visible in the Issues/Faults view’s fault queue and can be acknowledged/assigned by the PM without leaving this dashboard (FR-3).
The Battery PM can answer “what’s been out of commission too long” from the Issues/Faults view’s SLA/aging breakdown alone (FR-9).
Any battery’s full history (identity + every event + both SoH tiers) is reachable in two clicks from the fleet table, replacing the manual lookups the two Google Sheets currently require.
The two Google Sheets currently used for battery tracking are no longer needed for any task this dashboard covers.

10. Cross-References

Battery API suite — endpoint contracts already defined (location TBD at time of writing; not yet in this repo). The source of truth this dashboard reads from and writes triage events to.
VP, Battery dashboard — separate, future PRD. Higher-altitude, fleet-wide financial and strategic reporting. Do not conflate with this persona.
Battery Identity & Lifecycle PRD — products/rechaj-inventory-app/docs/TH-Battery Identity & Lifecycle PRD-210526-155643.pdf. Prior art on the Serial↔BMS identity model; relationship to the new API suite is an open question (§8.1).
Battery Identity Admin flow — products/atlas/flows/battery-identity-admin/index.html. Prior art on an execution surface for battery lifecycle actions; relationship to this dashboard’s fault-hand-off is an open question (§8.1).
Not to be confused with: the “Battery packs” nav module inside the Swap PM / VP / Super-Admin / Cluster-Manager / Support personas (site/src/data/products.ts) — a swap-operations-scoped battery-pack register owned by the Swap business unit, unrelated to this Tricycle-Hardware-owned Battery PM dashboard.