Wattr Operator App
Visual Specification

App overview

The fleet-control companion for scheme staff — many pumps, one operator.

Wattr Operator is used by scheme operators and Junior Engineers (JEs) to monitor and control the pumps in their scope: a filterable fleet dashboard, per-pump detail with live readings and start/stop, run-session history with export, per-pump schedules, automation settings, and a push-notification inbox. Where the farmer app serves one person's 1–15 pumps, this app is built for hundreds (staging tenant 41: 503 pumps).

Roles

Architecture in brief

• State: Riverpod 3 (providers per feature, autoDispose where re-entry should refetch). HTTP: single Dio client, base URL hard-coded to https://staging-api.wattr.ai/v1 (no build-time override — a known gap), Bearer token injected by interceptor, one automatic retry after POST /auth/refresh on 401.
• Navigation: no router package. An AuthGate switches Splash / Login / Dashboard on auth state; everything else is imperative Navigator.push. Push notifications deep-link through a global navigator key.
• Layout convention: feature-first (features/<name>/data·domain·presentation), shared code under core/.
• i18n: same mechanism as the farmer app — the English string is the dictionary key, WText looks it up, hi.json/pa.json hold ~245 entries each, language persists under wattr.language. Server-rendered notification text is deliberately never re-translated.
• Tokens are stored in SharedPreferences (wattr_access_token / wattr_refresh_token / wattr_user) — not secure storage.

Design system

Material 3 seeded from brand teal, Inter throughout, full light + dark themes following the OS setting.

Source: lib/core/constants/app_colors.dart · app_text_styles.dart · app_dimensions.dart · lib/core/theme/app_theme.dart

Brand & surfaces (light)

Status colors (the 3-tier scheme)

Resolved design decision (docs/prd-vs-design-discrepancies.md §1): faults render amber, not red — red means "not running, for any reason" (shutdown, bypass, remote stop, power loss). Color is never the only signal; every state also carries an icon and a text caption.

Dark theme

Full dark palette ships and follows the OS: background #0B0F19, surface #161B26, text #F9FAFB, muted #9CA3AF, border #2A3040, input fill #1F2937. The status tints have no dark variants — the light backgrounds (#E6F4EA / #FFF4DE / #FCE8E8) are reused as-is in dark mode.

Typography

One family — Inter (variable, bundled) with Noto Sans Devanagari / Gurmukhi fallbacks for Hindi and Punjabi. Scale: display 32/700 · headline 24/700 · titleLarge 20/600 (app bar) · titleMedium 16/600 · body 16 & 14/400 · labelLarge 14/600 (buttons) · bodySmall 12/400. No serif, no monospace — numerics use Inter.

Dimensions & shared widgets

4-pt spacing grid (4/8/16/24/32/48), radii 8/12/20/pill, buttons and inputs 52 px tall, inputs filled #F9FAFB with 12 px radius and a 1.5 px teal focus border.

Splash, login & shell

AuthGate switches Splash → Login → Dashboard; a drawer carries account-level actions.

Source: lib/features/splash/ · lib/features/auth/ · lib/features/shell/presentation/widgets/app_drawer.dart

9:41▲ ▂▄▆ ▮

⚡

wattr

Watts & Water. Forever.

9:41▲ ▂▄▆ ▮

🌐 English

Operator Console

Sign In

Enter your credentials to continue

Username

👤 Enter your username

Password

🔒 Enter your password👁

ⓘ Use your registered email and password

Sign In

Powered by Wattr.ai

Ravinder Singh

Junior Engineer

---

🔔Notification History

🎚Notification Preferences

🌐LanguageEnglish ⌄

---

⎋Logout

Behavior notes

• Splash is a plain teal #0F6E5C screen with the orange bolt + "wattr" wordmark (raw Text, never translated). Shown only while restoreSession() runs: stored token → GET /users/current; 401/403 clears tokens; network/5xx falls back optimistically to the cached user.
• Login: fields disable while submitting; client validation "Please enter username and password" (no network call); server errors show in a fixed light-red banner (#FCE8E8 — does not adapt to dark mode). Network failure → "Connection failed. Check your network."; otherwise "Invalid credentials" or the server's message. Language chip (top-right) opens the same en/hi/pa sheet as the drawer.
• Drawer: name (fallback email, then "—") + role label ("Junior Engineer" / "Operator"), Notification History, Notification Preferences, a Language dropdown row, and Logout (red icon) with the confirmation "Sign out? — You will need to sign in again to continue." (Cancel / Yes, sign out). Logout clears tokens but keeps the language preference.
• Auth API: POST /auth/login (usernameOrEmail + password), GET /users/current, POST /auth/logout (best-effort), POST /auth/refresh.

Dashboard (pump list)

The home screen: summary tiles that are also filters, search, a filter/sort sheet, and an infinite-scrolling fleet list.

Source: lib/features/dashboard/ · docs/pump-list-api-contract.md

Pump detail

One pump's full state: status hero, live readings, mode control, schedule preview, phase health, and a pinned action bar.

Source: lib/features/pump_detail/

Running times

Run-session history with range presets, a daily-runtime bar chart, a short-run anomaly flag, and CSV/Excel export.

Source: lib/features/running_times/

Schedules

Per-pump schedule list with a pause-all switch, and a bottom-sheet create/edit form. Capped at 16 slots (firmware limit).

Source: lib/features/schedules/

Behavior

• Names are always "Untitled schedule" in real data — the backend never populates name.
• Status pills: Paused (amber, when pause-all is on — wins over everything) · Active (green) · Inactive (amber). Row toggles disable while pause-all is on.
• Pause all: confirmation only when pausing ("Pause all schedules? — All schedules for this pump stop running until you resume them."); resuming is immediate. Auto-Mode pumps show an amber banner: "This pump is in Auto Mode, so schedules are overridden and will not run until Auto Mode is turned off in Settings."
• Validation (in order): "Pick at least one day." (inline, red, clears on tap) · "Set a start time." · "Enter a duration between 1 and 1440 minutes." · "End time must be after the start time." · "Duration must fit before the end time." Setting an end time triggers the hard-end confirmation: "Set an end time? — The pump will stop at this time even if the run has not finished. A run cut short is marked incomplete."
• Delete: "Delete schedule? — This removes the schedule permanently." with a red Delete button; snackbar "Schedule deleted".
• Cap: adding beyond 16 slots is blocked client-side: "You can add up to 16 schedules per pump."
• Server errors render verbatim (by design — they name the conflicting schedule): overlap 400, Auto-Mode 409, read-only tenant 403.
• API: GET/POST /pumps/:id/schedules, PUT/DELETE …/:slotIndex, POST …/pause; day bitmask Sun=bit 0 (127 all, 62 Mon–Fri, 65 weekends); stop_time is server-derived; every mutation returns the full slot list.

Settings

Deliberately automation-only: an Auto Mode switch and two timing fields. Language and sign-out live in the drawer, not here.

Source: lib/features/settings/ · docs/prd-vs-design-discrepancies.md §6.4

Notifications & push

An FCM-driven inbox with category filters, a six-toggle preferences screen, and deep links into pump detail.

Source: lib/core/push/push_service.dart · lib/features/notifications/

Push behavior

• Channels (IDs shared with the farmer app backend): critical_standard "Critical alerts" (heads-up + sound) and warning_silent "Warnings" (silent). The payload's tag: critical picks the channel.
• Routing: a tapped notification with pump_id opens that pump's detail; anything else opens Notification History. Those are the only payload keys the client acts on — title/body arrive server-rendered in the recipient's language and are never re-translated.
• Permission: if denied, one dialog per launch — "Turn on notifications — Notifications are off, so you won't get pump alerts. Turn them on for Wattr Operator." (Not now / Open Settings).
• Registration: PUT /user-devices/devices with {fcm_token, fcm_platform}; iOS waits for the APNS token (up to 10 × 500 ms).

Notification History

Cursor-paginated inbox (GET /notifications?limit=30) with category filter chips (All / Pump / Fault / Schedule / Weather), severity dots (red / warning / info), unread styling, optimistic mark-read and mark-all-read, and grouped rows ("…N times today" via group_count). The bell badge comes from GET /notifications/unread-count and is invalidated on push arrival, read actions, and pull-to-refresh.

Notification Preferences

Six per-type toggles, all default ON, saved optimistically via PUT /notification-preferences (silent rollback on failure): Power Down · Overvoltage · Undervoltage · Overload · Dry Run · Reverse Phase. Everything else (theft, no-signal, weather, schedule) is mandatory and ignores these toggles.

API reference

Every endpoint the operator app calls. Base: https://staging-api.wattr.ai/v1 (hard-coded), Bearer JWT, one auto-retry via POST /auth/refresh.

Shared client-side error copy: "Check your connection and try again." (no response) · "Something went wrong. Please try again." (anything else) · server error.message rendered verbatim when present.

Known gaps & notes