Repository navigation
ADR 0084 Area Clear Confirmation On Native Surfaces
Accepted (2026-11-14)
MowDeck starts a machine with blades remotely. The web app asks before every user-initiated start of blade movement or remote motion (start, resume, spot run, manual drive, leave dock, schedules, chat and AI assist): the area must be clear of people, children and animals, and the user supervises the mower as its manufacturer's manual describes. That check is a client safeguard on top of the server's safety rules (ADR 0012); it stores nothing on the server. Its pull request (#367) left the native surfaces out: the medium widget's Start (ADR 0059), the "Start mowing" App Intent that Siri and Shortcuts can run, and the Apple Watch app's Start (ADR 0060) still started the mower with one tap. App Review (guideline 1.4, physical harm) and plain safety need the same question there.
The native code was searched for every command that makes the mower move. Native code sends only start_mow (widget button, StartMowingIntent, the watch's Start relayed by the iPhone); resume_mow exists in the client but no surface sends it; there is no native drive, spot run or schedule control. The Live Activity and the watch complication have no buttons (tapping opens the app or the watch app). Android has no native controls (the web app runs in the shell and brings its own check).
Apple's constraints:
- An interactive widget runs its App Intent in the widget extension's process, without UI (Adding interactivity to widgets and Live Activities). Apple's documented way for a widget interaction that opens the app is
LinkorwidgetURL.openAppWhenRun"generates an error if the app intent runs in an app extension" (openAppWhenRun), so an intent button in this extension cannot hand over to the app either. - Siri and Shortcuts show a confirmation for an intent that calls
requestConfirmation:requestConfirmation(conditions:actionName:dialog:)from iOS 18, whose default conditions are empty, that is always ask (documentation); on iOS 17 (the widget extension's deployment target)requestConfirmation(result:confirmationActionName:showPrompt:), deprecated from iOS 18. Both return when the user confirms and throw when they cancel. - SwiftUI's
confirmationDialogworks on watchOS 10 (the watch app already uses it for the emergency stop).
One policy, one wording, in MowerWidgetCore. MotionCommandPolicy.needsAreaClearConfirmation(_:) is an exhaustive switch over MotionCommand (the Fleet command kinds native code can send): start_mow and resume_mow are asked; pause_mow, return_to_dock and emergency_stop never are, stopping is never delayed. Every surface asks the policy and none decides by itself. AreaClearWording holds the text, the web app's safety_title, safety_statement and safety_confirm in English and German, as Localizable.strings resources of the package (one catalog for the app, the widget extension and the watch; a unit test checks both languages are complete). Nothing is remembered: every start asks again, as on the web.
Per surface:
| Surface | Before | Now | Apple API |
|---|---|---|---|
| Medium widget, Start | intent button, one tap | a Link to mowdeck://mowers/<id>?confirm=start (AreaClearLink). The app shows a system alert (title, mower name, statement, "Confirm" / "Cancel") and only after "Confirm" sends the start natively with the widget credential; "Cancel" sends nothing. Without the app's interception the web app would open the mower page and ignore the query |
Link; UIAlertController in the app |
| Widget Pause, Station | intent buttons | unchanged, one tap | Button(intent:) |
Siri and Shortcuts, "Start mowing" (StartMowingIntent) |
started at once | asks before sending; cancelling throws and sends nothing |
requestConfirmation(actionName:dialog:) on iOS 18, requestConfirmation(result:confirmationActionName:showPrompt:) on iOS 17 |
| Apple Watch, Start | one tap |
confirmationDialog with the same wording; the message to the iPhone carries areaClear: true, and the iPhone refuses a start without it while parsing (bad_request), so an older or forged watch message cannot start the mower unasked |
SwiftUI confirmationDialog
|
| Apple Watch, Pause, Station, emergency stop | one tap (stop: its own confirmation) | unchanged | |
| Live Activity, watch complication | no buttons | nothing to guard |
The confirmation link only ever brings up the question; whoever opens it (another app, a web page) cannot start the mower through it.
The decision for the widget was between asking in the extension (not possible: no UI in the intent's process), dropping Start from the widget (loses a feature the owner uses), and opening the app. Opening the app costs one more step and shows the same question as everywhere else.
Accessibility. System alerts and confirmation dialogs support VoiceOver and Dynamic Type. The watch's Start and the widget's Start get an accessibility hint saying they ask first (the widget's: it opens MowDeck to confirm). After the app sent the start, VoiceOver announces "Start sent."
Server unchanged. As on the web, this is a client safeguard; no "confirmed at" or other field goes to the server, and the server validates every command as before (ADR 0012).
- A start from the widget opens the app; Pause and Station still work without it. The user guides say so.
- A new native command that moves the mower does not compile until
MotionCommandPolicydecides about it; a new surface asks the policy and usesAreaClearWording. - The wording is kept in step with the web app by hand (the unit test pins the English title and statement to the web text).
- A watch app older than this change cannot start the mower (the iPhone refuses its unconfirmed start); watch and iPhone app ship together, so this lasts only until the watch app updates.
- Pull requests that touch the Swift code, the Xcode project or the app scripts now compile the app, the extensions and the watch app unsigned and run the package tests on a macOS runner (job
iosin ci.yml); before, only the TestFlight run compiled them. - What a device must show and CI cannot: the Siri and Shortcuts prompt (spoken and shown), the widget link opening the app on a cold and a warm start, and the watch dialog. The owner checks them on the next TestFlight build (mobile apps).
Mirrored from docs/adr/0084-area-clear-confirmation-on-native-surfaces.md at commit 486d902bc6ed1a38fa761c7017c1080b4ee2cd02. Edit the file in the repository, not this wiki page.
Mirrored from the docs/ directory at commit 486d902bc6ed1a38fa761c7017c1080b4ee2cd02. Edit the files in the repository, not this wiki.
MowDeck documentation
- Home
- Phases
- Architecture
-
Decisions (ADR)
- Architecture decisions
- ADR 0001: OpenFGA instead of self-built authorization
- ADR 0002: Self-built Identity service in FastAPI instead of Keycloak or Zitadel
- ADR 0003: SvelteKit for the web app
- ADR 0004: Monorepo with a uv workspace
- ADR 0005: AGPL-3.0 for services and apps, Apache-2.0 for libraries
- ADR 0006: PostgreSQL for all persistence, no SQLite
- ADR 0007: NATS JetStream as event bus
- ADR 0008: Traefik as gateway
- ADR 0009: Command and event envelopes, subject naming and de-duplication
- ADR 0010: Python 3.13 for all services and libraries
- ADR 0011: Separate GPL-3.0 package for the PyMammotion adapter
- ADR 0012: Mower control interface and safety rules
- ADR 0013: Device-Gateway registry, sharding and per-mower concurrency
- ADR 0014: Authorization model, tuple ownership and the mowdeck-authz client
- ADR 0015: Tokens, sessions and key rotation
- ADR 0016: Fleet commands and authorization per command kind
- ADR 0017: Telemetry storage and retention
- ADR 0018: Realtime WebSocket protocol
- ADR 0019: Mammotion adapter transports, manual drive and secrets
- ADR 0020: Web app architecture
- ADR 0021: Browser authentication flow
- ADR 0022: Notifications: rules, recipients and delivery
- ADR 0023: Map rendering and projection
- ADR 0024: Scheduler: recurrence, rain pause and command issuing
- ADR 0025: Home Assistant integration as a pure API client
- ADR 0026: Manual drive channel over the Realtime WebSocket
- ADR 0027: Health history and theft alarm
- ADR 0028: Entitlements: plans as data and enforcement
- ADR 0029: Helm chart and release pipeline
- ADR 0030: Mowing patterns as plug-ins and the Planner
- ADR 0031: Billing with a Stripe adapter
- ADR 0032: Live camera over Agora, joined directly by the browser
- ADR 0033: Vision-assisted recovery with human approval
- ADR 0034: Linked cloud accounts and device discovery
- ADR 0035: Server-side camera frames and automatic AI analysis on errors
- ADR 0036: Native app shells with Capacitor, loading the web app from the server
- ADR 0037: Camera panorama calibration in the browser, with the AI supplying points only
- ADR 0038: Dual link per mower and firmware updates
- ADR 0039: Spot mowing by MowDeck-driven paths
- ADR 0040: Link heartbeat for online status
- ADR 0041: Spot runs from the dock: undock, transit and return
- ADR 0042: Drive calibration
- ADR 0043: Turn styles
- ADR 0044: Drive view with camera
- ADR 0045: Camera relay
- ADR 0046: Device settings as capabilities
- ADR 0047: The RTK base station as a Fleet device
- ADR 0048: Maintenance commands
- ADR 0049: Manual driving over the Mammotion cloud
- ADR 0050: Passkeys and the app login hand-off
- ADR 0051: Sign in with GitHub
- ADR 0052: Sign in with Apple
- ADR 0053: Retention and downsampling of the position track
- ADR 0054: Aerial photo under the mower map
- ADR 0055: Deploy maintenance window
- ADR 0056: Camera photo in push notifications for errors and theft alarms
- ADR 0057: Step-up re-authentication for critical actions
- ADR 0058: Theft tracking mode
- ADR 0059: iOS widgets and the mowing Live Activity
- ADR 0060: Apple Watch app
- ADR 0061: Mowing angle rotation
- ADR 0062: Setup tour for new users
- ADR 0063: Matter server (mowers in Apple Home and Google Home)
- ADR 0064: Personal access tokens and the public API documentation
- ADR 0065: Security center and new-login alerts
- ADR 0066: Cloud provider plugins and adapters for more vendors
- ADR 0067: Error code lexicon, provider independent
- ADR 0068: Public demo mode
- ADR 0069: Provider conformance kit and provider package template
- ADR 0070: Virtual zones for mowers without a vendor map
- ADR 0071: Capability matrix generated from the adapters
- ADR 0072: API explorer in the web app, for the public demo
- ADR 0073: Guided tour with coach marks
- ADR 0074: NATS authentication and per-service subject permissions
- ADR 0075: Chat control as an optional assistant add-on
- ADR 0076: Demo sandboxes, one account per visitor
- ADR 0077: Liveness, readiness and routing
- ADR 0078: Batched state ingestion
- ADR 0079: Fast demo sandbox claim and release
- ADR 0080: GitHub Codespaces dev container with the full Compose stack
- ADR 0081: Explicit consent before camera pictures or text go to a cloud AI provider
- ADR 0082: Deleting your own account inside the app
- ADR 0083: Payments ledger and operator dashboard
- ADR 0084: Area-clear confirmation on the native surfaces
-
Development
- Getting started
- Service template
- Shared libraries
- Cloud providers: adding a vendor
- Adding a provider: template and conformance kit
- Adding an error lexicon for a vendor
- Design: identity and authorization
- Design: fleet, telemetry, realtime
- Design: web app
- Web app
- Home Assistant integration
- Camera source bridge protocol
- Security assurance case
- Fuzzing and property-based tests
- CI and pull request scope
- Reproducible builds
- GitHub wiki mirror
-
Operations
- Operating the Compose stack
- Operating MowDeck on Kubernetes (Helm)
- Internal TLS
- Building the Bluetooth bridge (ESPHome on a XIAO ESP32-S3)
- Releases
- Vendor library updates
- Billing operations
- Telemetry: retention and position downsampling
- iPhone and Android apps
- Passkeys
- Sign in with GitHub
- Aerial photo under the map
- Sign in with Apple
- Theft tracking mode
- Matter server
- Chat control (assistant add-on)
- Source code offer (AGPL-3.0 section 13)
- Public demo
- Load testing
- Spikes
-
Guides
- Guides
- ESP32 bridge: purchase and setup
- Signing in with a passkey
- Signing in with GitHub
- Error codes in plain words
- Aerial photo under the map
- Signing in with Apple
- Confirming critical actions
- Your security page
- Deleting your account or yourself
- iPhone widgets and the mowing Live Activity
- Apple Watch
- The setup tour
- Apple Home and Google Home (Matter)
- Chat control
- Worx Landroid, Kress and LandXcape mowers
- Scripting MowDeck
- Capability matrix
- API reference
- Original plan (German)