System Requirements Document for smart-micro-grid

1. Introduction

smart-micro-grid is a dark-mode operations console for a small off-grid solar + storage micro-grid. It presents live telemetry from an ESP32 node (solar panel output, battery state of charge, environmental irradiance and temperature), the Random Forest prediction and Energy Management System (EMS) decision state, the physical relay switch panel, and a running system activity log — all on one instrument-style dashboard.

The product intent is instrument-panel calm under a live failure event: an operator must be able to read the current system state at a glance, see what the AI decided and why, and confirm that the primary load (LED) is still being supplied while the secondary load (DC fan) has been shed. The audience is technical — an operator who watches the grid and a technician who manages the relay hardware — and the interface is designed to be trusted at 2am when the battery is falling.

The design system is fixed by the user: Dark Mode / Slate Dark ground (#0F172A), Slate Container cards (#1E293B) with #334155 hairline strokes, primary text #F8FAFC, muted text #94A3B8, metric numerals #38BDF8, and status indicators green #16A34A / yellow #FACC15 / red #EF4444, in a sans-serif family (Inter or Roboto). The layout is a Mobile PWA targeting 390px, where telemetry cards stack into a single column and the bottom area collapses to one column with the Relay Control panel above the Activity Log.

2. System Overview

smart-micro-grid is delivered as a first-party web application (Mobile PWA) with a backend that durably retains telemetry, EMS decisions, relay state, and activity log entries. The ESP32 device is the telemetry source and relay actuator; the Random Forest model and EMS logic produce the predictive load-shedding decision; the dashboard is the human-facing surface where both accepted personas read state and act.

Current delivery and actors. Two accepted human personas use the product: the Operator Dashboard Micro-Grid, who monitors real-time telemetry and EMS/AI decisions to ensure the primary load keeps receiving power, and the Teknisi/Pengelola Perangkat Relay, who works the relay switch panel and follows up on EMS decisions recorded in the activity log. The ESP32 device, the Random Forest model, and the EMS engine are typed non-persona actors — they produce telemetry, predictions, and decisions, but they are not human users.

Accepted behavior. The dashboard shows a header with the wordmark and two status pills (ESP32 connection and AUTO (AI) mode), three real-time telemetry cards (solar panel, battery SoC, environmental sensor), a full-width Smart Engine banner carrying the Random Forest prediction and the EMS decision state, a relay control panel with per-relay status badges, and a terminal-style activity log. The layout is responsive: three telemetry columns at desktop, a single stacked column at 390px; the bottom area is two columns at desktop and one column at 390px with Relay Control above Activity Log.

Ownership and access. The application owns identity. The Landing page is an anonymous public entry that explains the micro-grid, telemetry monitoring, EMS decisions, and relay control before authentication. The Login page is the returning-verification surface for the operator and technician. The Dashboard is the protected workspace where telemetry, EMS state, relay control, and the activity log live; it is role-restricted to authenticated operators and technicians. Provisioning or invitation of operator and technician access is a prerequisite to first use, and returning verification through Login is required before the Dashboard can be reached.

Narrow exclusions. This document does not add adjacent capabilities beyond the accepted thread: no consumer-style account management, no social features, no marketing site beyond the anonymous Landing entry, no additional pages, and no product behavior beyond the telemetry, EMS, relay, and log surfaces described here. The generic indigo/blue-on-white SaaS template is explicitly forbidden for this project.

2a. Product Interpretation and Delivery Boundary

The product is a single-purpose operations console, not a general-purpose dashboard platform. Its delivery boundary is: a first-party web application (Mobile PWA) with an application-owned identity layer, a backend that persists telemetry, EMS decisions, relay state, and log entries, and an ESP32 device plus Random Forest/EMS engine that supply the live data and decisions. The human-facing surfaces are the anonymous Landing entry, the Login verification surface, and the protected Dashboard workspace.

Everything the user specified is current: the dark slate design system, the header with ESP32 and AUTO (AI) pills, the three telemetry cards, the Smart Engine banner, the relay control panel, the activity log terminal, and the 390px mobile stacking rules. The identity layer (provisioning/invitation, Login verification, protected Dashboard) is required inference — it exists only to make the accepted journeys executable and to keep relay state and log history bound to the correct participant. No future-horizon features are declared in the source; the current scope is the complete scope.

2b. Source Content Inventory

Not applicable — no reference directive in this request declares content_source authority. All product facts come from the authoritative user requirement thread and the Planning Scope contract.

2c. Page Content and Component Coverage

Landing

• Information / state: Anonymous public entry. Explains what the Smart Micro-Grid is, that it monitors real-time telemetry (solar panel, battery SoC, environmental sensor), that a Random Forest + EMS engine makes predictive load-shedding decisions, and that relay control is available after sign-in. No live telemetry values are shown to anonymous visitors; the page describes the system and routes to Login.
• Primary actions: Navigate to Login to verify identity and reach the Dashboard.
• Supporting actions: Read the system description; understand the ESP32 / AUTO (AI) / EMS concepts before signing in.
• Domain entities: Micro-grid system description, telemetry categories (solar, battery, environment), EMS/AI concept, relay concept.
• Component responsibilities: Wordmark "\xe2\x9a\xa1 Smart Micro-Grid Dashboard" (18px bold, #F8FAFC); short system description in Inter Tight body text; a single primary action routing to Login. No telemetry cards, no relay controls, no log on this page.
• States: Loading (page shell renders immediately; no data fetch required). Empty (not applicable — static explanatory content). Success (description renders, Login action available). Error (if the Login route is unreachable, show a muted inline message and keep the description readable). Recovery (retry the navigation action).

Login

• Information / state: Returning-verification surface for the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay. Accepts credentials established during provisioning/invitation. On success, routes to the protected Dashboard.
• Primary actions: Submit credentials to verify identity and enter the Dashboard.
• Supporting actions: Return to Landing; correct a mistyped credential.
• Domain entities: Operator identity, technician identity, session.
• Component responsibilities: Credential input fields; submit control; inline validation and error messaging; link back to Landing. Styled with the same dark slate ground, #1E293B surface, #334155 hairline border, #F8FAFC text, #94A3B8 muted labels.
• States: Loading (submit control shows a pending state while verification runs). Empty (fields empty on first render). Success (verification succeeds, redirect to Dashboard). Error (invalid credentials — inline error in #EF4444, fields remain editable, no partial session is created). Recovery (re-submit after correcting input; return to Landing if access was never provisioned).

Dashboard

• Information / state: The protected workspace. Shows the header with wordmark and two status pills; three real-time telemetry cards; the full-width Smart Engine banner; the relay control panel; and the activity log terminal. All values are live and update as telemetry arrives. The page is role-restricted to authenticated operators and technicians.
• Primary actions: Read live telemetry; read the EMS prediction and decision; read relay state; read the activity log; the technician acts on relay state through the relay control panel.
• Supporting actions: Observe the ESP32 connection pill and AUTO (AI) mode pill; observe the predictive load-shedding badge and action description; follow the log entries that record EMS decisions.
• Domain entities: Telemetry reading (solar power W, panel voltage V, panel current mA; battery SoC %, battery voltage V, safety label; irradiance W/m², temperature °C, weather label); ESP32 connection status; AUTO (AI) mode; Random Forest prediction (2-hour-ahead power supply, Watt); EMS decision status (Predictive Load Shedding Active); relay (Relay 1 Lampu LED Utama, Relay 2 Kipas DC Sekunder) with ON/OFF state; activity log entry (timestamp, source, message, severity).
• Component responsibilities:
  • Header / Top Navigation Bar: Left — "\xe2\x9a\xa1 Smart Micro-Grid Dashboard" (bold, 18px, #F8FAFC). Right — Badge "ESP32: ONLINE" (pill, fill #16A34A, white text 11px bold) and Badge "MODE: AUTO (AI)" (pill, fill #0284C7, white text 11px bold).
  • Telemetry Card 1 — PANEL SURYA: Title "PANEL SURYA" (#94A3B8, 12px bold); primary metric "0.91 W" (#38BDF8, 28px bold, tabular numerals); detail "5.10 V | 180 mA" (#CBD5E1, 12px).
  • Telemetry Card 2 — KONDISI BATERAI (SOC): Title "KONDISI BATERAI (SOC)" (#94A3B8, 12px bold); primary metric "78%" (#4ADE80, 28px bold, tabular numerals); detail "Tegangan: 3.95 V (Aman)" (#CBD5E1, 12px).
  • Telemetry Card 3 — SENSOR LINGKUNGAN: Title "SENSOR LINGKUNGAN" (#94A3B8, 12px bold); primary metric "650 W/m²" (#FACC15, 28px bold, tabular numerals); detail "Suhu: 31.5 °C (Terik)" (#CBD5E1, 12px).
  • Smart Engine Banner (full width): Background #312E81, border #6366F1. Header left "\xf0\x9f\xa4\x96 SMART ENGINE (Random Forest & EMS)" (#A5B4FC, 14px bold). Badge right "⚠️ PREDIKSI PENURUNAN DAYA" (pill #EF4444, white text 11px bold). Info row 1 "Prediksi Pasokan Daya (2 Jam Ke Depan): 0.25 Watt" (white text, numeral #38BDF8 bold). Info row 2 "Status Keputusan: Predictive Load Shedding Active" (#FBBF24 bold). Action description "Aksi Sistem: Mematikan Beban Sekunder (Kipas DC) secara proaktif agar Beban Utama (LED) tetap mendapat pasokan daya." (#CBD5E1, 12px).
  • Relay Control Panel (left column at desktop, top of bottom area at 390px): Title "\xf0\x9f\x8e\x9b️ PANEL KONTROL SAKELAR (RELAY)" (13px bold). Mode status "● Mode Otomatis (AI Engine Active)" (#38BDF8, 12px). Horizontal divider. Row "Relay 1: Lampu LED (Utama)" with badge "ON" (fill #22C55E, white bold). Row "Relay 2: Kipas DC (Sekunder)" with badge "OFF (AI)" (fill #EF4444, white bold).
  • Activity Log Panel (right column at desktop, bottom of bottom area at 390px): Title "\xf0\x9f\x93\x8b LOG AKTIVITAS SISTEM" (13px bold). Terminal box background #020617, monospace 11px. Log lines: "[14:10:05] ESP32 kirim telemetri: V=5.1V, I=180mA" (#94A3B8); "[14:10:07] RF prediksi daya turun 40%" (#94A3B8); "[14:10:08] EMS Load Shedding: Relay 2 OFF" (#F87171); "[14:10:10] Relay 1 tetap dijaga ON" (#4ADE80).
• Responsive behavior: At ≥1024px the three telemetry cards sit in three parallel columns and the bottom area is two columns (Relay Control left, Activity Log right). At 390px the three telemetry cards stack into a single vertical column and the bottom area becomes a single column with the Relay Control panel above the Activity Log.
• States: Loading (skeleton or pending state for telemetry cards, EMS banner, relay rows, and log while the first payload arrives). Empty (no telemetry yet — cards show a muted placeholder, log shows an empty terminal state). Success (live values render, EMS decision and relay state visible, log lines append). Error (ESP32 offline — the ESP32 pill reflects the disconnected state and telemetry cards show a stale/unavailable indicator; log records the disconnection). Recovery (when telemetry resumes, cards repopulate and the ESP32 pill returns to ONLINE; the log records the recovery).

3. Functional Requirements

FR-1 — Dark Mode / Slate Dark design system. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should see the dashboard rendered on a Dark Mode / Slate Dark ground (#0F172A) with Slate Container cards (#1E293B) bordered by #334155, so that the console reads as a low-light instrument panel. Provenance: explicit. Lifecycle: actor — both personas; trigger — page render; observable result — background #0F172A, cards #1E293B with #334155 stroke; failure/recovery — not applicable (static styling); continuation — all other dashboard surfaces inherit the same ground and surface tokens.

FR-2 — Header / Top Navigation Bar. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should see a header with "\xe2\x9a\xa1 Smart Micro-Grid Dashboard" (bold, 18px, #F8FAFC) on the left and two status pills on the right — "ESP32: ONLINE" (pill, fill #16A34A, white text 11px bold) and "MODE: AUTO (AI)" (pill, fill #0284C7, white text 11px bold) — so that I can confirm the device connection and the active control mode at a glance. Provenance: explicit. Lifecycle: actor — both personas; trigger — dashboard load; observable result — wordmark and both pills render with the specified fills and labels; failure/recovery — if the ESP32 is not connected, the ESP32 pill reflects the disconnected state; continuation — the header remains visible above all dashboard content.

FR-3 — Real-time telemetry card row (3 parallel columns). As the Operator Dashboard Micro-Grid, I should see three real-time telemetry cards in parallel columns — "PANEL SURYA" with primary metric "0.91 W" (#38BDF8, 28px bold) and detail "5.10 V | 180 mA" (#CBD5E1, 12px); "KONDISI BATERAI (SOC)" with primary metric "78%" (#4ADE80, 28px bold) and detail "Tegangan: 3.95 V (Aman)" (#CBD5E1, 12px); and "SENSOR LINGKUNGAN" with primary metric "650 W/m²" (#FACC15, 28px bold) and detail "Suhu: 31.5 °C (Terik)" (#CBD5E1, 12px) — so that I can read the current energy and environmental state in one row. Provenance: explicit. Lifecycle: actor — Operator; trigger — telemetry payload arrives; observable result — each card shows its title (#94A3B8, 12px bold), primary metric, and detail line; failure/recovery — if telemetry is unavailable, the affected card shows a stale/unavailable indicator and repopulates when data resumes; continuation — the operator continues monitoring the remaining cards and the EMS banner.

FR-4 — Smart Engine AI & EMS decision banner (full width). As the Operator Dashboard Micro-Grid, I should see a full-width banner with background #312E81 and border #6366F1, header "\xf0\x9f\xa4\x96 SMART ENGINE (Random Forest & EMS)" (#A5B4FC, 14px bold), badge "⚠️ PREDIKSI PENURUNAN DAYA" (pill #EF4444, white text 11px bold), info row "Prediksi Pasokan Daya (2 Jam Ke Depan): 0.25 Watt" (white text, numeral #38BDF8 bold), info row "Status Keputusan: Predictive Load Shedding Active" (#FBBF24 bold), and action description "Aksi Sistem: Mematikan Beban Sekunder (Kipas DC) secara proaktif agar Beban Utama (LED) tetap mendapat pasokan daya." (#CBD5E1, 12px) — so that I understand what the model predicted and what the EMS decided to do about it. Provenance: explicit. Lifecycle: actor — Operator; trigger — Random Forest prediction and EMS decision are produced; observable result — banner shows the 2-hour-ahead prediction, the decision status, and the plain-language action description; failure/recovery — if the prediction or decision is unavailable, the banner shows a pending/unavailable state and updates when the next decision arrives; continuation — the operator cross-checks the relay panel and log against the stated decision.

FR-5 — Relay control panel (left column at desktop). As the Teknisi/Pengelola Perangkat Relay, I should see a relay control panel titled "\xf0\x9f\x8e\x9b️ PANEL KONTROL SAKELAR (RELAY)" (13px bold) with mode status "● Mode Otomatis (AI Engine Active)" (#38BDF8, 12px), a horizontal divider, row "Relay 1: Lampu LED (Utama)" with badge "ON" (fill #22C55E, white bold), and row "Relay 2: Kipas DC (Sekunder)" with badge "OFF (AI)" (fill #EF4444, white bold) — so that I can see the current relay state and confirm the EMS has shed the secondary load while keeping the primary load on. Provenance: explicit. Lifecycle: actor — Teknisi; trigger — relay state is read from the backend; observable result — each relay row shows its label and its current badge; failure/recovery — if relay state cannot be read, the affected row shows an unavailable indicator and refreshes when state is restored; continuation — the technician follows up on the EMS decision recorded in the activity log.

FR-6 — Activity log terminal (right column at desktop). As the Teknisi/Pengelola Perangkat Relay, I should see an activity log panel titled "\xf0\x9f\x93\x8b LOG AKTIVITAS SISTEM" (13px bold) with a terminal box on background #020617 in monospace 11px, containing lines "[14:10:05] ESP32 kirim telemetri: V=5.1V, I=180mA" (#94A3B8), "[14:10:07] RF prediksi daya turun 40%" (#94A3B8), "[14:10:08] EMS Load Shedding: Relay 2 OFF" (#F87171), and "[14:10:10] Relay 1 tetap dijaga ON" (#4ADE80) — so that I can trace the sequence of telemetry, prediction, and EMS action. Provenance: explicit. Lifecycle: actor — Teknisi; trigger — system events are recorded; observable result — log lines append in the terminal with severity colouring; failure/recovery — if the log stream is interrupted, the terminal shows a gap indicator and resumes appending when the stream returns; continuation — the technician uses the log to confirm the EMS decision matches the relay state.

FR-7 — Typography and status colour system. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should see sans-serif typography (Inter or Roboto) with primary text #F8FAFC, secondary/muted text #94A3B8, metric numerals #38BDF8, and status indicators green #16A34A, yellow #FACC15, red #EF4444 — so that the console is legible and status is unambiguous. Provenance: explicit. Lifecycle: actor — both personas; trigger — page render; observable result — text and status colours match the specified tokens; failure/recovery — not applicable (static styling); continuation — all dashboard surfaces use the same type and status tokens.

FR-8 — Mobile PWA 390px responsive layout. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should see the layout adapt at 390px so that the three telemetry cards stack into a single vertical column and the bottom area becomes a single column with the Relay Control panel above the Activity Log — so that the console remains usable on a phone. Provenance: explicit. Lifecycle: actor — both personas; trigger — viewport at 390px; observable result — telemetry cards stack vertically, Relay Control sits above Activity Log; failure/recovery — not applicable (layout rule); continuation — the operator and technician can read and act on the same information as at desktop.

FR-9 — Provisioning or invitation of operator and technician access. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should be provisioned or invited before first use, so that my access to the protected Dashboard is established. Provenance: required_inference. Lifecycle: actor — both personas; trigger — first use; observable result — an access credential is established for the operator and the technician; failure/recovery — if provisioning is not completed, the Login page cannot grant access and the user is directed back to Landing; continuation — the user proceeds to Login for returning verification.

FR-10 — Returning verification through Login. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should verify my identity through Login before accessing the Dashboard, so that relay state and log history remain bound to the correct participant. Provenance: required_inference. Lifecycle: actor — both personas; trigger — navigating to the Dashboard; observable result — on successful verification the user reaches the Dashboard; failure/recovery — invalid credentials produce an inline error and no session is created; continuation — the user retries or returns to Landing.

FR-11 — Durable backend for telemetry, EMS decisions, relay state, and log. As the Operator Dashboard Micro-Grid and the Teknisi/Pengelola Perangkat Relay, I should have telemetry, EMS decisions, relay state, and activity log entries retained durably by the backend, so that the Dashboard reflects the current and recent state of the micro-grid. Provenance: required_inference. Lifecycle: actor — both personas (as readers of persisted state); trigger — telemetry and decisions arrive from the ESP32 and EMS engine; observable result — the Dashboard reads current telemetry, EMS decision, relay state, and log from the backend; failure/recovery — if the backend is unreachable, the Dashboard shows an unavailable state and recovers when the backend returns; continuation — the operator and technician continue monitoring once state is restored.

4. User Personas

Operator Dashboard Micro-Grid

Product context. The Operator watches a small off-grid solar + storage micro-grid through a single dark-mode console. The system is small enough that one person can hold the whole state in view: a solar panel, a battery, an environmental sensor, a Random Forest prediction, an EMS decision, two relays, and a log. The operator's job is to know, at any moment, whether the primary load (LED) is still being supplied and whether the secondary load (DC fan) has been shed.

Primary goal. Detect critical conditions early and confirm that predictive load shedding is keeping the primary load active.

Distinct accepted responsibilities. The operator reads the three real-time telemetry cards (solar panel output, battery SoC, environmental irradiance and temperature), reads the Smart Engine banner to understand the 2-hour-ahead power prediction and the EMS decision status, and watches the ESP32 connection pill and the AUTO (AI) mode pill to confirm the system is online and running in automatic mode. The operator's work is monitoring and interpretation — reading the instrument, not turning the knobs.

Relevant inputs or decisions. The operator's inputs are the live telemetry values, the Random Forest prediction, the EMS decision status, and the activity log. The operator's decision is whether the current state is safe or whether a critical condition is developing — for example, whether the battery SoC and the predicted power supply together indicate that the primary load is at risk.

Interactions with other accepted participants. The operator reads the same relay state and activity log that the Teknisi/Pengelola Perangkat Relay acts on. When the EMS decides to shed the secondary load, the operator sees the decision in the banner and the resulting relay state in the relay panel; the technician sees the same decision in the log and confirms the relay state. The operator does not control the relays — that is the technician's responsibility.

Observable success. The operator succeeds when a critical condition is detected early and the predictive load shedding keeps the primary load (LED) active — visible as Relay 1 ON, Relay 2 OFF (AI), and a log line confirming "Relay 1 tetap dijaga ON".

Teknisi/Pengelola Perangkat Relay

Product context. The Technician manages the relay hardware behind the micro-grid. Where the operator reads the instrument, the technician works the switch panel: Relay 1 (Lampu LED, primary) and Relay 2 (Kipas DC, secondary). The technician's context is the relay control panel and the activity log, and the technician's job is to make sure the physical relay state matches what the EMS decided.

Primary goal. Ensure the relay state matches the EMS decision and that the action is recorded in the activity log.

Distinct accepted responsibilities. The technician reads the relay control panel — the mode status "● Mode Otomatis (AI Engine Active)", the divider, and the two relay rows with their ON / OFF (AI) badges — and follows up on the EMS decisions recorded in the activity log, including the proactive load-shedding action. The technician's work is verification and follow-up on hardware state, not telemetry interpretation.

Relevant inputs or decisions. The technician's inputs are the relay state badges, the mode status, and the activity log entries (telemetry received, RF prediction, EMS load shedding, Relay 1 maintained ON). The technician's decision is whether the relay state is consistent with the EMS decision and whether any follow-up is needed.

Interactions with other accepted participants. The technician acts on the same EMS decision the operator reads in the Smart Engine banner. When the EMS sheds the secondary load, the technician sees "EMS Load Shedding: Relay 2 OFF" in the log and confirms Relay 2 shows OFF (AI) in the relay panel, while Relay 1 remains ON.

Observable success. The technician succeeds when the relay state matches the EMS decision and the action is recorded in the activity log — Relay 1 ON, Relay 2 OFF (AI), and log lines that trace the telemetry, prediction, and EMS action in order.

5. Core User Flows

Flow 1 — Operator monitors the micro-grid and confirms the primary load is safe

1. Starting context. The Operator has been provisioned with access and has verified identity through Login. The Dashboard is open on the protected workspace.
2. Read the header. The operator sees "\xe2\x9a\xa1 Smart Micro-Grid Dashboard" on the left and the two status pills on the right: "ESP32: ONLINE" (green #16A34A) and "MODE: AUTO (AI)" (blue #0284C7). The operator confirms the device is connected and the system is in automatic mode.
3. Read the telemetry cards. The operator reads the three cards in parallel columns: "PANEL SURYA" showing "0.91 W" with detail "5.10 V | 180 mA"; "KONDISI BATERAI (SOC)" showing "78%" with detail "Tegangan: 3.95 V (Aman)"; and "SENSOR LINGKUNGAN" showing "650 W/m²" with detail "Suhu: 31.5 °C (Terik)".
4. Read the Smart Engine banner. The operator reads the full-width banner: header "\xf0\x9f\xa4\x96 SMART ENGINE (Random Forest & EMS)", badge "⚠️ PREDIKSI PENURUNAN DAYA", info row "Prediksi Pasokan Daya (2 Jam Ke Depan): 0.25 Watt", info row "Status Keputusan: Predictive Load Shedding Active", and the action description explaining that the system is proactively turning off the secondary load (DC fan) so the primary load (LED) keeps receiving power.
5. Interpret the decision. The operator understands that the model predicts a power drop and the EMS has decided to shed the secondary load. The operator's decision is whether the current state is safe — with the battery at 78% and the primary load protected, the operator judges the state as safe.
6. Observable result. The operator sees Relay 1 ON and Relay 2 OFF (AI) in the relay panel, and the activity log shows the sequence: telemetry received, RF prediction of a 40% power drop, EMS load shedding of Relay 2, and Relay 1 maintained ON.
7. Failure / recovery. If the ESP32 pill shows a disconnected state, the operator sees the affected telemetry cards show a stale/unavailable indicator and the log records the disconnection. When telemetry resumes, the cards repopulate, the ESP32 pill returns to ONLINE, and the log records the recovery. The operator continues monitoring.
8. Continuation. The operator keeps the Dashboard open and continues watching the telemetry cards and the EMS banner for the next prediction or decision.

Flow 2 — Technician verifies relay state against the EMS decision

1. Starting context. The Teknisi/Pengelola Perangkat Relay has been provisioned with access and has verified identity through Login. The Dashboard is open on the protected workspace.
2. Read the relay control panel. The technician reads the panel titled "\xf0\x9f\x8e\x9b️ PANEL KONTROL SAKELAR (RELAY)" with mode status "● Mode Otomatis (AI Engine Active)", the horizontal divider, and the two relay rows: "Relay 1: Lampu LED (Utama)" with badge "ON" (green #22C55E) and "Relay 2: Kipas DC (Sekunder)" with badge "OFF (AI)" (red #EF4444).
3. Read the activity log. The technician reads the terminal box titled "\xf0\x9f\x93\x8b LOG AKTIVITAS SISTEM" on background #020617 in monospace 11px, and traces the lines: "[14:10:05] ESP32 kirim telemetri: V=5.1V, I=180mA", "[14:10:07] RF prediksi daya turun 40%", "[14:10:08] EMS Load Shedding: Relay 2 OFF", "[14:10:10] Relay 1 tetap dijaga ON".
4. Verify consistency. The technician's decision is whether the relay state matches the EMS decision. Relay 2 shows OFF (AI) and the log shows "EMS Load Shedding: Relay 2 OFF" — consistent. Relay 1 shows ON and the log shows "Relay 1 tetap dijaga ON" — consistent.
5. Observable result. The technician confirms that the relay state matches the EMS decision and that the action is recorded in the activity log.
6. Failure / recovery. If a relay row shows an unavailable indicator, the technician waits for state to be restored and re-reads the row; if the log stream is interrupted, the terminal shows a gap indicator and resumes appending when the stream returns. The technician re-verifies consistency once state is restored.
7. Continuation. The technician continues to follow up on subsequent EMS decisions recorded in the log, confirming each time that the relay state matches.

Flow 3 — First-use access for operator and technician

1. Starting context. A new operator or technician has no access yet. They arrive at the anonymous Landing page.
2. Read the Landing page. The visitor reads the description of the Smart Micro-Grid — real-time telemetry (solar panel, battery SoC, environmental sensor), the Random Forest + EMS engine, and relay control — and understands that the Dashboard is behind sign-in.
3. Provisioning / invitation. The operator or technician is provisioned or invited, establishing their access credential. (If provisioning is not completed, the Login page cannot grant access and the user is directed back to Landing.)
4. Verify identity through Login. The user submits their credentials on the Login page. On success, they are routed to the protected Dashboard.
5. Observable result. The user reaches the Dashboard and sees the header, telemetry cards, Smart Engine banner, relay panel, and activity log.
6. Failure / recovery. If credentials are invalid, the Login page shows an inline error in #EF4444, no session is created, and the user can correct the input and re-submit or return to Landing.
7. Continuation. The user proceeds to their role's work — the operator to Flow 1, the technician to Flow 2.

6. Visuals Colors and Theme

Muse and headline. Systematic instrument craft after Rasmus Andersson — "the numbers ARE the interface." The console is an instrument panel, not a marketing page: dark graphite ground, hairline borders, tabular numerals as ornament, and one hot non-blue accent (amber) reserved for machine decisions.

Colour tokens (dark mode).

Proportion. Roughly 62% ground, 30% surface panels, 6% numerals and status fills, 2% amber. Amber is reserved exclusively for machine-authored / AI-decided state — the "OFF (AI)" relay badge stroke, the RF prediction tick, and the predictive-shedding rule — and must stay scarce or it stops meaning anything.

Typography. Headings Space Grotesk 500/700 for the wordmark, panel titles, and the large metric numerals, with tight tracking (-0.02em) on headings. Tabular numerals (font-variant-numeric: tabular-nums) are mandatory on every metric so 0.91 W / 78% / 650 W/m² align in a column across cards. Uppercase micro-labels at 11–12px with +0.08em letterspacing for card titles and section eyebrows. Body Inter Tight 400/500 for body, log lines, and detail strings at 12–13px. Where the user wrote "Inter or Roboto", Inter Tight is the characterful sibling that satisfies the request while carrying real personality; Roboto is not used. Log monospace JetBrains Mono 11px/1.7 — the only monospace allowed.

Type scale. 1.25 modular on a 4px baseline: 11 / 12 / 13 / 14 / 18 / 28 / 40 / clamp(56px, 9vw, 104px). Micro-labels 11px +0.08em; card titles 12px bold uppercase; detail strings 12px; EMS header 14px bold; nav wordmark 18px bold; metric numerals 28px (mobile 26px) bold tabular; page display headline clamp(56px, 9vw, 104px) at 500 weight, tracking -0.03em, max 3 lines.

Shape language. Engineered flatness. 8px radius on cards and panels, 6px on badges and pills, 4px on inline status chips — one radius family, no blob, no 24px softness. Depth is expressed as a 1px #334155 hairline on every container edge plus a 1px inner top highlight at rgba(248,250,252,0.04) to suggest a machined bezel. No drop shadows anywhere. Status is carried by a 3px left rule on the container edge (green/amber/red) plus a small solid-fill pill; never by a glow. Relay rows are separated by full-width 1px #334155 rules that run edge to edge inside the panel, like a rack unit. Dividers are structural, not decorative.

Spacing rhythm. Strictly 4 / 8 / 12 / 16 / 24 / 32. A strict 12-column grid, 24px gutters, max content width 1440px, page padding 16px at 375px / 24px at 768px / 40px at 1280px.

Imagery style. The interface is the imagery. No stock photography, no 3D renders, no gradient blobs, no illustration. Visual assets are: a 96px-tall live power sparkline drawn as a 1.5px #38BDF8 polyline on a #0F172A ground with hairline gridlines at 25/50/75%; a small circular SoC gauge rendered as a 1px #334155 ring with a #4ADE80 arc; a 24-cell solar-irradiance bar row where cells fill #FACC15; a battery-cell pictogram drawn as 4 stacked 6px rounded rects. Any icon is a 1.5px-stroke geometric mark on a 16 or 20px grid, drawn to the same stroke weight as the hairlines. The log terminal is a real terminal: #020617 ground, 11px JetBrains Mono, colour-coded by severity.

Avoid. Blue-on-white SaaS look — the palette is locked dark slate and must never invert. Any gradient, glow, blur, glassmorphism, or drop shadow; depth comes from 1px hairlines and value steps only. Inter, Roboto, Arial, Helvetica, Poppins, or system-ui as the heading or body family. Centred hero with a headline, subtext, and a blue CTA. A grid of identical rounded cards with hover-lift. Blob shapes, 24px+ radii, pill-shaped everything, sticker or badge illustration. Amber used for anything other than machine/AI-authored state. Bouncy, springy, or scroll-reveal motion.

7. Signature Design Concept

The live instrument header. The public entry (Landing) is not a marketing hero — it is a live instrument header that introduces the console. Full-bleed #0F172A, no gradient, no centred stack.

Composition. The left third holds an oversized display line set in Space Grotesk 500 at clamp(56px, 9vw, 104px) reading the current system state as a sentence — "78%" on line one, "DAN BEBAN UTAMA AMAN" set much smaller beneath it in 14px Inter Tight #94A3B8 — so the largest object on the page is a live number, not a slogan. The right two-thirds is a 96px-tall sparkline rail spanning to the viewport edge, with a 1px #334155 baseline and the current point marked by a 6px #38BDF8 dot with a hairline vertical drop to the axis. Directly beneath, a single hairline rule runs the full viewport width; below it, three small monospace metadata blocks (#94A3B8 labels, #F8FAFC values) sit on the 12-column grid. The nav sits above all of it, hairline-bottomed, wordmark left, ESP32 and AUTO pills right. Nothing is centred, nothing floats, and there is no button in the hero — the hero is the reading.

Signature moves.

• Oversized live numeral as the hero: the SoC percentage set at clamp(56px, 9vw, 104px) in Space Grotesk 500 with tabular numerals, flush left on the 12-column grid, with a 14px muted caption beneath it — the page's largest object is a value that changes.
• Numeral column alignment across telemetry cards: all three metric numerals (0.91 W, 78%, 650 W/m²) are tabular and share one baseline grid, so they read as a single instrument readout rather than three marketing cards.
• A 96px live sparkline rail that bleeds to the right viewport edge with a hairline axis and a drop-line to the current point — the only full-bleed element on the page, and it is data, not decoration.
• Amber as the machine-authored signal: a #F59E0B hairline and stroke on anything the AI decided (the "OFF (AI)" relay badge outline, the RF prediction row, the predictive-shedding rule), so a human can tell at a glance what the operator did versus what the model did.
• Relay rows built as rack-unit rows: full-width 1px #334155 rules running edge to edge inside the panel with a 3px status rule on the container's left edge, so the control panel reads as hardware, not as a settings list.

This concept only recomposes accepted content, states, and controls — it introduces no new behavior, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief. Focal subject: the oversized live SoC numeral and the 96px sparkline rail. Input → transformation → outcome thesis: as telemetry updates arrive, the hero numeral cross-fades to the new value and the sparkline appends a new point — the reading stays current without the page ever animating for decoration. Motion vocabulary: 120ms for hover and focus, 200ms for value changes, cubic-bezier(0.2, 0, 0, 1); one purposeful loop only — live metric numerals cross-fade on telemetry update (old value fades up 4px out, new fades down in), a state change, not an animation. The EMS banner carries a single 1.2s amber tick travelling along its top hairline when predictive load shedding is active, then stops. Relay toggles snap with no bounce. The sparkline rail draws its path once on load over 600ms, then appends points without re-animating. No parallax, no scroll reveals, no particles. Composed first frame: full-bleed #0F172A, nav hairline-bottomed with wordmark left and ESP32 / AUTO pills right, oversized "78%" flush left with the muted caption beneath, sparkline rail bleeding to the right viewport edge with the current point marked, hairline rule beneath, three monospace metadata blocks on the 12-column grid. Reduced-motion state: under prefers-reduced-motion, the numeral cross-fade becomes an instant value swap, the amber tick becomes a static amber hairline, and the sparkline renders its full path immediately without the 600ms draw.

9. Non-Functional Requirements

NFR-1 — Dark Mode / Slate Dark design system (hard constraint). The interface must use Dark Mode / Slate Dark (#0F172A) as the ground, Slate Container (#1E293B) for cards, and #334155 stroke borders. Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-2 — Status indicator colours (hard constraint). Status indicators must follow: green active/safe #16A34A, yellow warning #FACC15, red critical/load shedding #EF4444. Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-3 — Sans-serif typography (hard constraint). The font must be sans-serif (Inter or Roboto). Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-4 — Mobile PWA 390px layout (hard constraint). The mobile layout targets a 390px viewport with telemetry cards in a single column and the bottom area in a single column (Relay Control above Activity Log). Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-5 — Durable state retention. Telemetry, EMS decisions, relay state, and activity log entries must be retained durably by the backend so the Dashboard reflects current and recent state. Provenance: required_inference. Rationale: required to make the accepted monitoring and follow-up journeys executable.

NFR-6 — Readable text and controls at every viewport. Headlines, wordmarks, labels, numbers, card text, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element may cover any part of them. Provenance: explicit (creative direction). Rationale: the console must remain legible and operable on the target mobile PWA and at desktop widths.

NFR-7 — Reduced-motion support. Under prefers-reduced-motion, the numeral cross-fade becomes an instant value swap, the amber tick becomes a static amber hairline, and the sparkline renders its full path immediately. Provenance: explicit (creative direction). Rationale: the console must remain usable for users who prefer reduced motion.

10. Tech Stack

• Frontend: React (web), delivered as a Mobile PWA targeting 390px. Dark-mode design system per Section 6.
• Backend: Python / FastAPI, providing the API for telemetry, EMS decisions, relay state, and activity log.
• Storage: A durable store for telemetry, EMS decisions, relay state, and activity log entries (relational or time-series store appropriate to the retained data).
• Device / model: ESP32 node supplying telemetry and actuating relays; Random Forest model producing the 2-hour-ahead power prediction; EMS engine producing the load-shedding decision.
• Containerization: Docker / docker-compose for local and deployment packaging. Kubernetes is not required by the source and is not included.

11. Assumptions and Constraints

• A-1 (assumption). The ESP32 device, the Random Forest model, and the EMS engine are external to the dashboard application and supply telemetry, predictions, and decisions through the backend. Label: assumption — not specified by user.
• A-2 (assumption). The numeric values shown in the design system (0.91 W, 5.10 V, 180 mA, 78%, 3.95 V, 650 W/m², 31.5 °C, 0.25 Watt, and the log timestamps) are the specified display values for the dashboard's current state and are rendered as live values from the backend. Label: assumption — not specified by user.
• A-3 (assumption). The relay control panel shows relay state; the source specifies the ON / OFF (AI) badges and the automatic mode status but does not specify a manual override control, so no manual override is added. Label: assumption — not specified by user.
• C-1 (constraint). The design system is fixed: Dark Mode / Slate Dark (#0F172A), Slate Container (#1E293B) with #334155 stroke, primary text #F8FAFC, muted #94A3B8, metric numerals #38BDF8, status green #16A34A / yellow #FACC15 / red #EF4444, sans-serif (Inter or Roboto). Provenance: explicit.
• C-2 (constraint). The mobile layout targets a 390px Mobile PWA with telemetry cards stacked in one column and the bottom area in one column (Relay Control above Activity Log). Provenance: explicit.
• C-3 (constraint). The generic indigo/blue-on-white SaaS template is forbidden for this project. Provenance: explicit (creative direction).
• C-4 (constraint). The Dashboard is role-restricted to authenticated operators and technicians; the Landing page is anonymous; the Login page is the returning-verification surface. Provenance: required_inference.

12. Glossary

• Micro-grid: The small off-grid solar + storage system monitored and controlled by this product.
• ESP32: The device node that sends telemetry and actuates the relays.
• Telemetry: The live readings from the micro-grid — solar panel power/voltage/current, battery state of charge and voltage, and environmental irradiance and temperature.
• SoC (State of Charge): The battery's remaining charge, shown as a percentage.
• Random Forest (RF): The machine-learning model that predicts the power supply for the next 2 hours.
• EMS (Energy Management System): The logic that turns the Random Forest prediction into a control decision, including predictive load shedding.
• Predictive Load Shedding: The proactive decision to turn off the secondary load (DC fan) so the primary load (LED) keeps receiving power.
• Relay 1 — Lampu LED (Utama): The primary load relay, kept ON to maintain the main light.
• Relay 2 — Kipas DC (Sekunder): The secondary load relay, shed by the EMS when power is predicted to drop.
• AUTO (AI) mode: The operating mode in which the EMS/AI engine controls the relays automatically.
• Activity Log: The terminal-style record of system events — telemetry received, RF prediction, EMS load shedding, and relay state changes.
• Mobile PWA: The progressive web app delivery targeting a 390px phone viewport.