Wattr Farmer App
Visual Specification

App overview

What the app is, who uses it, and how it fits into the Wattr platform.

Wattr Farmer is the mobile companion to the Wattr.ai water-pump monitoring platform (PHMC). It lets farmers monitor and control their IoT-connected water pumps from their phone, schedule irrigation, and see farm-relevant weather and modelled soil conditions. It also carries a safety-critical feature: a full-screen theft alarm (SOS) that takes over the phone when a pump's controller detects tampering. Mandi prices, a conservation rewards program, and water-quota tracking are designed and partially built, but deliberately parked until real data feeds exist (Chapter 17 has the full status map).

The platform behind it monitors ~5,400 devices and ~4,400 pumps across 54 tenants in 8 Indian states. The app talks to the same backend API as the web dashboard.

Who uses it

The UI is the same for every role — what changes is the data scope the API returns. There is no separate "admin mode" in the app.

Environments

You can switch environments from inside the app: long-press the logo on the login screen (dev toggle). Staging test credentials are listed in the repo README.md — never commit or share them outside the team.

Tech stack at a glance

Architecture & code map

Feature-first layered architecture: cross-cutting code in core/, everything else owned by a feature.

lib/
├── main.dart                  # Bootstrap only — binding init, translator init, runApp
├── app.dart                   # WattrApp: MaterialApp + auth gate (splash / login / home)
│                              #   + global SOS overlay + desktop max-width clamp
├── core/
│   ├── constants/             # app_prefs.dart (SharedPreferences keys), quota.dart
│   ├── i18n/                  # translator.dart — TranslatorProvider (en / hi / pa)
│   ├── network/               # api_client.dart, service_error.dart
│   ├── push/                  # FCM + local notifications + SOS controller/permissions
│   ├── theme/                 # colors.dart (class C), typography.dart
│   ├── utils/                 # format.dart
│   └── widgets/               # WText, AppCard, PillBadge, SectionLabel, ArcGauge, charts
└── features/<name>/
    ├── data/datasources/      # *_service.dart — API calls; models live alongside
    ├── domain/entities/       # pure-Dart entities (FarmerProfile, Tier)
    └── presentation/
        ├── screens/           # full-page widgets
        └── widgets/           # feature-private sub-widgets

Rules a new joinee must know

• State stays local. setState unless state genuinely crosses widget boundaries — today only TranslatorProvider (language) and SosController (theft alarm) qualify for Provider. Don't introduce Riverpod/Bloc/GetX.
• Services own HTTP. Screens never build requests; they call *Service classes which use the shared ApiClient (adds JWT, handles errors as ServiceError).
• Models double as entities. No DTO/entity split — pragmatic classes returned straight from services.
• All user-visible text is rendered with WText, which looks up the string in the active language dictionary — the English string itself is the translation key. Adding UI copy means adding the matching entries to assets/i18n/hi.json and pa.json.
• Text scale is clamped app-wide to 0.85–1.1× so huge OS font settings can't break layouts; on windows wider than 1024 px content is centered in an 800 px column.

Docs worth reading next

• README.md — build/run instructions, test accounts, API status table
• docs/sos-theft-alert.md & docs/ios-sos-lockscreen.md — theft alarm design
• docs/scheduling-status-report.md & docs/scheduling-v1-deferred.md — scheduling scope and deferred items
• API_REQUIREMENTS.md — backend endpoints the app expects

Design system

A calm, light, green-on-cream identity. Tokens live in core/theme/colors.dart (class C) and core/theme/typography.dart. This document itself is set in the app's palette and typefaces.

Color — the C palette

Green primary on a Tailwind-ish 50–900 scale, plus accent families (sky, sun, lime, earth, red), surface tones, and four text shades. Backgrounds are never pure white-on-white: the scaffold is a faint green-tinted off-white with white cards and mint borders.

Primary greens

Accent families & semantic colors

Surfaces, borders & text

Typography

Three top-level helper functions in typography.dart — call sites use them everywhere instead of raw TextStyles. All three attach a Noto Sans Gurmukhi fallback so Punjabi (ਪੰਜਾਬੀ) renders with an intentional typeface.

Shared widgets (core/widgets/)

Internationalization

Three languages ship in assets/i18n/: English, Hindi (hi.json, ~457 entries), Punjabi (pa.json, ~460 entries). The mechanism is unusual and worth understanding: the English string is the translation key. WText('Good Morning') looks the literal string up in the active dictionary via TranslatorProvider; en.json is an identity map, so English needs no entries. The chosen language persists under the SharedPreferences key wattr.language, and pickers exist on both the login screen and the home header (globe icon). If a string is missing from hi.json/pa.json it silently renders in English — e.g. "Good Afternoon" and "Good Evening" are currently untranslated.

Shell, splash & navigation

One authenticated mode, five tabs, everything wired through FarmerHome.

Source: lib/app.dart · lib/features/dashboard/presentation/screens/farmer_home.dart

The auth gate

WattrApp decides what to show with two booleans — there is no router or named routes:

_initialising ? SplashScreen
: _authenticated ? FarmerHome(onLogout)
                 : LoginScreen(onLoginSuccess)

On launch, AuthService.restoreSession() checks for a stored token and validates it against GET /users/current. An authoritative 401 clears tokens and shows Login; a network failure or 5xx optimistically keeps the user signed in so the app works offline. There is no role check anywhere in the client — every signed-in user gets the same FarmerHome.

9:41▲ ▂▄▆ ▮

WATTR.AI

GS

Good Morning

Gurpreet Singh

🌐

🔔 3

— active tab renders here (IndexedStack) —

🏠Home

☁️Weather

💧

Pump

🌿Soil

🏪Market

Header anatomy

1. Avatar — 44 px circle, green gradient, 2 px translucent white ring. Shows the initials of the first two words of the profile name ("Gurpreet Singh" → GS; falls back to "F" for the placeholder name "Farmer"). Tap → pushes the Profile screen.
2. Greeting + name — greeting picked by local hour: before 12 "Good Morning", before 17 "Good Afternoon", else "Good Evening" (DM Sans 11, white). Name below in Fraunces 16 bold white; literal "Farmer" until the profile loads.
3. Language button — globe icon in a frosted 40 px circle. Opens the Choose Language bottom sheet (English / हिन्दी / ਪੰਜਾਬੀ).
4. Notification bell — same circle, with a red badge (#DC2626, caps at "9+") when unread alerts exist. Tap → pushes the Alerts screen. Note: the count is fetched once at launch (GET /alerts/unread-count) and never refreshed afterwards.

The header background is solid C.p700 #15803D with a subtle dot-grid overlay (1 px white dots at 8% opacity on an 18 px lattice). There is no Material AppBar, no drawer, and no FAB anywhere in the app — the elevated center Pump button plays the FAB role.

Tab map

The body is an IndexedStack, so all tabs stay alive — switching tabs never loses scroll position or state. Active tab is marked by a 28×3 px green pill that animates in above the icon (200 ms).

Live-data engine (what FarmerHome runs in the background)

Shared sheets & toasts

Command snackbars float above the nav bar (rounded 12 px, green #16A34A for success with a ✓, red #DC2626 for errors with a ⚠). The full message set, verbatim:

• "Start command sent — confirming…" / "Stop command sent — confirming…"
• "Start failed: <reason>" / "Stop failed: <reason>"
• "Could not start pump. Check your connection." / "Could not stop pump. Check your connection."
• "Device is offline — no response from pump. Check connectivity and try again." (30 s timeout)
• "No pump configured" · "Pump identifier missing — pull to refresh and try again"

First-run permission dialogs (Android)

Right after login, the app checks the two permissions the theft alarm needs to take over a locked screen, prompting one at a time and only when missing:

1. "Allow full-screen theft alerts" — "So the loud theft alarm can take over your screen when your phone is locked, allow full-screen alerts for Wattr." (Android 14+ full-screen intent)
2. "Allow display over lock screen" — "Some phones also need 'Display over other apps' so the theft alarm can appear over the lock screen." (OEMs like ColorOS)

Actions: Not now / Open Settings; returning from Settings re-checks the next permission automatically.

Login

Username + password sign-in on a deep-green gradient. No registration, no forgot-password, no OTP.

Source: lib/features/authentication/presentation/screens/login_screen.dart · auth_service.dart

9:41▲ ▂▄▆ ▮

🌐 English

WATTR.AI

Farm Water Intelligence

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

v1.0.0

Anatomy

1. Language chip (top-right) — frosted pill with globe icon; opens the same language sheet as the home header. The whole screen re-renders in the picked language instantly.
2. Logo block — 90 px rounded logo with a green glow shadow, "WATTR.AI" in Fraunces 32, tagline "Farm Water Intelligence" in mint #86EFAC. The column fades/slides in over 900 ms on mount.
3. Sign-in card — white, 28 px radius. Fields have grey #F9FAFB fills and #E5E7EB borders that turn green #22C55E on focus. The eye icon toggles password visibility. "Next" on the keyboard moves username → password; "Done" submits.
4. Sign In button — full-width, 54 px, #16A34A. While the request runs it turns pale green #86EFAC with a white spinner.
5. Footer — "Powered by WATTR.AI" and a version string. ⚠ The version is hard-coded "v1.0.0" while pubspec.yaml is at 1.0.2+7 — a known stale label.

States

ValidationEmpty fieldsTapping Sign In with an empty username or password shows "Please enter username and password" — no network call is made.

LoadingSigning inButton disabled (pale green) with a 22 px white spinner; fields stay editable.

ErrorAuth failedRed error box between the hint and the button: light red fill #FEF2F2, red border, ⓘ icon, server's message or "Login failed".

OfflineNo networkSame error box with "Connection failed. Check your network."

Hidden dev toggle

Long-press "Powered by WATTR.AI" to open the Server URL dialog — a plain text field pre-filled with the current base URL (default https://staging-api.wattr.ai/v1). Saving persists to SharedPreferences and takes effect on the next request. There is no validation and no visual confirmation — this is how you point a build at staging vs production.

API

POST /auth/login with {usernameOrEmail, password} → expects data.accessToken, data.refreshToken, data.user; tokens persist in SharedPreferences. Refresh is automatic: on the first 401/403 the client calls POST /auth/refresh once and replays the request.

Home tab

The at-a-glance farm summary: pick a pump, see the weather, control the pump, and peek at the two forecasts. Every card is a shortcut into a deeper tab.

Source: lib/features/home/presentation/screens/home_tab.dart · pump_picker_accordion.dart

Pumps

The heart of the app: live telemetry, remote start/stop, health diagnostics, sessions, and the wire-cut takeover. Four screens share this feature.

Source: lib/features/pumps/presentation/screens/ — pump_tab.dart · pump_list_screen.dart · pump_detail_screen.dart · recent_sessions_screen.dart

7.1 · Pump tab (the center tab, default on launch)

7.2 · Wire-cut (tamper) takeover

7.3 · Pump list & detail (legacy surfaces)

• PumpListScreen — reached from Profile ("View all N pumps") or the dead Dashboard. Data comes from the profile's embedded pumps[] (never GET /pumps, which 403s for farmers) plus one /telemetry/latest call per pump in parallel. Status is derived client-side: ON / OFF / UNKNOWN. No polling — refresh is manual. From Profile, tapping a pump selects it and jumps back to the Pump tab; otherwise it opens the swipeable detail pager.
• PumpDetailScreen / pager — full telemetry: status dot + Start/Stop side-by-side buttons (no stop confirmation here), POWER & ENERGY grid (Power / PF / Freq / kWh / Discharge / Temp), 3-phase voltage & current tiles (R red, Y amber, B blue), FAULT STATUS chips (only Dry Run / Overload / Overheat surfaced), and a DEVICE INFO key-value card. Polls every 15 s off / 30 s on; the pager gives each page its own timers and shows "N of M · swipe to browse" with page dots (≤10 pumps).
• RecentSessionsScreen — "Last 30 sessions / Past 7 days · <pump>": a clean table of Date · Time range (mono, en-dash) · Duration rows from GET /reports/start-stop?pump_id=…&last_n_sessions=30. Empty state: "No sessions in the past 7 days". Note: lib/screens/recent_sessions_screen.dart is a dead byte-identical legacy copy — the live one is under features/pumps/.

Irrigation schedules

Automated pump sessions: a schedule list with a global pause, a create/edit form with a hard-end cutoff, and a 7-day run history.

Source: lib/features/schedules/ — schedule_list_screen.dart · schedule_edit_screen.dart · occurrence_history_screen.dart · days_of_week_picker.dart

Key behaviors

• Global pause — the "All schedules" switch asks for confirmation ("Pause all schedules? All scheduled sessions will be paused… Individual schedule settings will be saved."). While paused, every row dims to 60% opacity, row toggles disable, and an amber banner reads "Scheduling is off — no sessions will run automatically until you turn it back on."
• Day picker — seven 40 px circles, Monday-first M T W T F S S; selected = filled #15803D. Under the hood the bitmask is firmware order with Sunday = bit 0 (127 = every day, 62 = Mon–Fri, 65 = weekends).
• Duration — bottom sheet with preset pills (15/30/45 min, 1 hour, 1h 30m, 2 hours) plus a free "min" field (1–1440).
• Hard end — an optional cutoff time. Saving with one set triggers the confirmation "Set end time as cutoff? … The pump will stop at this time even if the full N min duration hasn't been completed. The session will be marked Incomplete if cut short." Cancel strips the hard end and saves anyway; dismissing aborts.
• Validation (snackbars, in order): "Pick at least one day." · "Set a start time." · "Set a duration." · "End time must be after the start time." · "Duration must fit before the end time." Overlap conflicts come back from the API as 400s and surface verbatim.
• Per-row toggle is optimistic — flips instantly, PUTs the slot, reverts with an error snackbar on failure.
• Delete — trash icon → "Delete schedule? This removes "<name>" from this pump." with a red Delete button.

Run-history status chips (complete map)

API

GET/POST /pumps/:id/schedules · PUT/DELETE /pumps/:id/schedules/:slotIndex · POST /pumps/:id/schedules/pause {paused, confirm:true} · GET /pumps/:id/occurrences/history?from&to (7-day window) · GET /pumps/:id/occurrences/live. Times travel as IST HH:MM; every mutation returns the full slot list as source of truth.

Weather tab

Agricultural weather from the free Open-Meteo API — current conditions, irrigation-relevant advisories (ET₀ and VPD), a 24-hour temperature curve, precipitation, and a wind profile.

Source: lib/features/weather/presentation/screens/weather_tab.dart · weather_service.dart

Soil health tab

Modelled soil moisture and temperature at depth — honest about being model data, and deliberately silent on irrigation advice.

Source: lib/features/soil/presentation/screens/soil_tab.dart

Market (Mandi) tab

Today: a single honest "Coming Soon" card. Behind it sits a fully-designed mandi-price experience, deliberately disabled until a real data feed exists.

Source: lib/features/market/presentation/screens/market_tab.dart (1,342 lines, mostly dormant)

Rewards tab

A complete gamification screen — tier rank, weekly water challenge, points, leaderboard — kept unmounted because every number in it is fabricated.

Source: lib/features/rewards/presentation/screens/rewards_tab.dart · domain/entities/tier.dart

Alerts

Reached from the header bell. Today the screen is an intentional empty state — the dummy list was removed and the real feed hasn't landed yet.

Source: lib/features/alerts/ — alerts_screen.dart · alert_card.dart (currently unused) · alerts_service.dart

What exists vs. what renders

• AlertsService is real and used for the header badge: GET /alerts (optionally ?status=active|resolved), GET /alerts/unread-count, POST /alerts/:id/resolve. The screen itself makes no network call — it's a hardcoded empty state since the dummy data was removed (commit aa70123).
• AlertCard is a finished three-severity component (red / amber "sun" / green — colored background + 4 px left accent bar + optional action button) with zero call sites. Its action button is onPressed: () {} and resolveAlert has no callers.
• Severity vocabulary mismatch to resolve before wiring it up: the API speaks red / warning / info, the widget enum speaks red / sun / green, and FarmerAlert has no icon field though the card requires one.
• The header bell badge is fetched once at launch and never refreshed (Chapter 4).

Profile & settings

One pushed screen with two modes — a read-only card list, and an accordion edit form. Also home to the language switcher, the theft-alarm permission tile, and Sign Out.

Source: lib/features/profile/presentation/screens/profile_screen.dart (1,905 lines) · profile_service.dart · farmer_profile.dart

Reached by tapping the avatar in the home header (it's a pushed route, not a tab). The largest screen in the app: nine view-mode cards, an eight-section edit form, and the full pump-registration flow.

SOS theft alarm & push

The safety-critical feature: when a pump controller reports tampering, the phone becomes a siren — full-screen red takeover, looping alarm on the ALARM audio stream, forced max volume, and (on Android) a lock-screen takeover.

Source: lib/features/sos/presentation/sos_screen.dart · lib/core/push/ · docs/sos-theft-alert.md · docs/ios-sos-lockscreen.md

API reference

Every endpoint the app actually calls, in one table. Base: https://staging-api.wattr.ai/v1 (Bearer JWT; auto-refresh on first 401/403 via POST /auth/refresh).

Error copy is centralized in ServiceError.userMessage: "No network — check your connection and try again." · "Session expired — please sign in again." · "Not found." · "Server error — please try again in a moment." · else the server's own message or "Request failed."

Dead services (implemented, zero call sites): QuotaService (/water-quota/current, /savings) and DashboardService (/dashboard/stats, /fault-summary, /power-hourly, /daily-aggregates — only reachable from the unmounted DashboardScreen).

Feature status & test data

The single most useful table for a new joinee: what's real, what's mock, and what's parked.

Testing on staging

Long-press the login footer to point a build at staging vs production. Staging test accounts (Super Admin with all pumps, plus two farmer accounts with 14 and 501 pumps respectively — useful for small-list vs big-list testing) are listed in the repo README.md. Treat them as secrets: don't paste them into docs, tickets, or screenshots.

First-week checklist for a new joinee

1. Run the app against staging (flutter run), sign in with a farmer account, and walk every tab with this doc open.
2. Read farmer_home.dart top to bottom — it owns all shared state and every timer.
3. Trigger a pump start on a staging pump and watch the "confirming…" → confirmed flow (and the 30 s offline path with an unplugged device).
4. Switch language to हिन्दी and note which strings fall back to English — untranslated strings are silent, not errors.
5. Skim the four docs in docs/ — they explain why scheduling and SOS look the way they do.