super-productivity/docs/long-term-plans/location-based-reminders.md

Location-Based Reminders — Design Document

Status: Planned (Brainstorm)

Overview

Add location-based reminders to Super Productivity. Users can attach a saved location to a task and receive a notification when they arrive at that place. This is primarily a mobile feature (Android/iOS via Capacitor), with passive location display on desktop/web.

Decisions

Decision	Choice	Rationale
Primary platform	Mobile (Android/iOS)	Geofencing requires GPS + background location. Desktop/web show location info but don't trigger.
Trigger type	Arrive only (v1)	Simplest. Leave triggers can be added later.
Location management	Saved locations entity	Users revisit the same places. Follows existing Tag entity pattern.
Location picker (v1)	"Use current location" + label	No map needed for v1. Map picker is a v2 enhancement.
Geofencing approach	Custom native Capacitor plugin	@capacitor/geolocation only does point-in-time reads, not geofencing. Need native GeofencingClient (Android) / CLLocationManager (iOS).
Sync	Sync by default	Location data treated like any other entity. Each device manages its own geofences locally after sync.
Feature toggle	isLocationRemindersEnabled in AppFeaturesConfig	Opt-in, default false.

---

1. Data Model

1.1 SavedLocation Entity

New file: src/app/features/saved-location/saved-location.model.ts

import { EntityState } from '@ngrx/entity';

export interface SavedLocationCopy {
  id: string;
  title: string;             // "Office", "Grocery Store", "Gym"
  lat: number;               // latitude
  lng: number;               // longitude
  radius: number;            // geofence radius in meters (default 200)
  icon?: string | null;      // material icon name, e.g. 'home', 'work', 'shopping_cart'
  created: number;           // creation timestamp
  modified?: number;         // last update timestamp
}

export type SavedLocation = Readonly<SavedLocationCopy>;
export type SavedLocationState = EntityState<SavedLocation>;

1.2 Task Model Changes

File: src/app/features/tasks/task.model.ts — add to TaskCopy:

/** ID of a SavedLocation. When set, a geofence reminder is active for this task. */
locationReminderId?: string | null;

1.3 Config Changes

File: src/app/features/config/global-config.model.ts — add to AppFeaturesConfig:

isLocationRemindersEnabled: boolean;  // default false

File: src/app/features/config/default-global-config.const.ts — set default:

isLocationRemindersEnabled: false,

1.4 Platform Capabilities

File: src/app/core/platform/platform-capabilities.model.ts — add:

/** Whether the platform supports native geofencing (background location monitoring). */
readonly geofencing: boolean;

Platform	geofencing
Android (ANDROID_CAPABILITIES)	true
iOS (IOS_CAPABILITIES)	true
Electron (ELECTRON_CAPABILITIES)	false
Web (WEB_CAPABILITIES)	false

---

2. Sync & Persistence Registration

All registration steps required for the new entity, following existing patterns:

2.1 Entity Type

File: packages/shared-schema/src/entity-types.ts

Add 'SAVED_LOCATION' to the ENTITY_TYPES array.

2.2 Action Types Enum

File: src/app/op-log/core/action-types.enum.ts

// SavedLocation actions
SAVED_LOCATION_ADD = '[SavedLocation] Add SavedLocation',
SAVED_LOCATION_UPDATE = '[SavedLocation] Update SavedLocation',
SAVED_LOCATION_DELETE = '[SavedLocation] Delete SavedLocation',

These string values are immutable once deployed — they are used for encoding/decoding operations in IndexedDB and sync between clients.

2.3 Entity Registry

File: src/app/op-log/core/entity-registry.ts

Add to ENTITY_CONFIGS:

SAVED_LOCATION: {
  storagePattern: 'adapter',
  featureName: SAVED_LOCATION_FEATURE_NAME,
  payloadKey: 'savedLocation',
  adapter: savedLocationAdapter,
  selectEntities: createSelector(
    selectSavedLocationFeatureState,
    selectSavedLocationEntitiesFromAdapter,
  ),
  selectById: selectSavedLocationById,
},

2.4 Model Config

File: src/app/op-log/model/model-config.ts

Add to AllModelConfig type:

savedLocation: ModelCfg<SavedLocationState>;

Add to MODEL_CONFIGS:

savedLocation: {
  defaultData: initialSavedLocationState,
  isMainFileModel: true,
  repair: fixEntityStateConsistency,
},

2.5 Root State

File: src/app/root-store/root-state.ts

[SAVED_LOCATION_FEATURE_NAME]: SavedLocationState;

2.6 Feature Store Registration

File: src/app/root-store/feature-stores.module.ts

StoreModule.forFeature(SAVED_LOCATION_FEATURE_NAME, savedLocationReducer),

2.7 Cascading Delete Meta-Reducer

File: src/app/root-store/meta/task-shared-meta-reducers/saved-location-shared.reducer.ts

When a SavedLocation is deleted, clear locationReminderId on all tasks that reference it. This must be a meta-reducer (not an effect) to ensure atomicity — one operation in the sync log.

Register in src/app/root-store/meta/meta-reducer-registry.ts in Phase 5 (Entity-Specific Cascades), alongside tagSharedMetaReducer, projectSharedMetaReducer, etc.

---

3. NgRx Store

3.1 Actions

File: src/app/features/saved-location/store/saved-location.actions.ts

Following the Tag action pattern with PersistentActionMeta:

Action	OpType	Payload
addSavedLocation	Create	{ savedLocation: SavedLocation }
updateSavedLocation	Update	{ savedLocation: Update<SavedLocation> }
deleteSavedLocation	Delete	{ id: string }

All include meta: { isPersistent: true, entityType: 'SAVED_LOCATION', entityId, opType } satisfies PersistentActionMeta.

3.2 Reducer

File: src/app/features/saved-location/store/saved-location.reducer.ts

Standard @ngrx/entity adapter:

export const SAVED_LOCATION_FEATURE_NAME = 'savedLocation';
export const savedLocationAdapter = createEntityAdapter<SavedLocation>({
  sortComparer: (a, b) => a.title.localeCompare(b.title),
});
export const initialSavedLocationState = savedLocationAdapter.getInitialState();

3.3 Selectors

File: src/app/features/saved-location/store/saved-location.selectors.ts

Selector	Returns
selectSavedLocationFeatureState	Feature state
selectAllSavedLocations	SavedLocation[]
selectSavedLocationById	SavedLocation | undefined
selectSavedLocationEntities	Dictionary<SavedLocation>

Task-side selector (in task selectors or a cross-feature selector):

Selector	Returns
selectTasksWithLocationReminder	All undone tasks that have locationReminderId set

3.4 Service

File: src/app/features/saved-location/saved-location.service.ts

Thin wrapper dispatching actions to the store. Methods: addSavedLocation(), updateSavedLocation(), deleteSavedLocation(), getById$().

---

4. Geofencing Service

4.1 Architecture

New file: src/app/features/saved-location/geofence.service.ts

Store (undone tasks with locationReminderId)
  → GeofenceService watches selector (distinctUntilChanged)
  → Computes which locations need active geofences
  → Registers/unregisters via custom Capacitor plugin
  → Receives geofence enter events
  → Emits to ReminderService for dialog/notification

4.2 Why a Custom Capacitor Plugin

@capacitor/geolocation only provides one-time and continuous position reads — it does not support geofencing. Native geofencing requires:

• Android: com.google.android.gms.location.GeofencingClient (Google Play Services). Supports up to 100 geofences. Fires BroadcastReceiver on enter/exit.
• iOS: CLLocationManager.startMonitoring(for: CLCircularRegion). Supports up to 20 monitored regions. Fires delegate callbacks on enter/exit.

Implementation: Create GeofencePlugin.kt (Android) and GeofencePlugin.swift (iOS) extending Capacitor's Plugin class. Register in CapacitorMainActivity.onCreate() following the pattern of SafBridgePlugin, WebDavHttpPlugin, etc.

4.3 Lifecycle Rules

Register geofence when:

• Feature is enabled + a task gets locationReminderId assigned
• App starts with existing location-reminded tasks

Unregister geofence when:

• Task is completed, deleted, or locationReminderId cleared
• SavedLocation is deleted
• No more undone tasks reference that location
• Feature is disabled

iOS 20-region limit: Only register geofences for the 20 locations with the most active tasks. Re-evaluate when tasks change.

4.4 Effects

Effects MUST use inject(LOCAL_ACTIONS) — geofence registration should never happen during remote sync replay. Each device manages its own geofences based on local state after sync.

4.5 Background Behavior

When geofence fires while app is in background:

• Android: BroadcastReceiver shows native notification directly (same pattern as ReminderAlarmReceiver). Tapping opens app + reminder dialog.
• iOS: CLLocationManager delegate fires local notification. Tapping opens app + reminder dialog.

4.6 Permission Flow

On first use:

1. Check CapacitorPlatformService.hasCapability('geofencing')
2. Request ACCESS_FINE_LOCATION + ACCESS_BACKGROUND_LOCATION (Android) or "Always" location access (iOS)
3. If denied: feature degrades to display-only, show explanation

---

5. Reminder Integration

5.1 Integration Point

The existing ReminderService.onRemindersActive$ is a derived observable — external code cannot emit to it directly. Two approaches:

Option A (recommended): Add a new public subject on ReminderService:

// In ReminderService
private _onLocationReminders$ = new Subject<TaskWithReminderData[]>();
locationReminders$ = this._onLocationReminders$.asObservable();

Then merge in ReminderModule:

merge(
  this._reminderService.onRemindersActive$,
  this._reminderService.locationReminders$,
).subscribe(reminders => /* existing dialog handling */);

Option B: Add a public method emitLocationReminders() that pushes to the private _onRemindersActive$ subject.

5.2 Data Shape

Location-triggered reminders must satisfy TaskWithReminderData:

interface TaskWithReminderData extends Task {
  readonly reminderData: { remindAt: number };  // use trigger timestamp
  readonly parentData?: Task;
  readonly isDeadlineReminder?: boolean;         // false for location
}

Consider adding isLocationReminder?: boolean for UI differentiation.

5.3 Dialog UX Changes

The existing DialogViewTaskRemindersComponent works as-is with minor additions:

• Show location name/icon in header (e.g., "At: Grocery Store")
• Snooze = suppress this location reminder for 1 hour (temporary geofence pause)
• Dismiss = clear locationReminderId on the task
• Done = mark task complete (same as today)
• Hide "Edit Reminder" time picker for location-triggered reminders

5.4 Native Notifications (Background)

Reuse CapacitorReminderService patterns:

• Android: native notification via ReminderNotificationHelper triggered from geofence BroadcastReceiver
• iOS: LocalNotifications.schedule() triggered from CLLocationManager delegate
• Both support Done/Snooze action buttons

---

6. UI Components

6.1 New Components

Component	Path	Purpose
saved-location-settings	src/app/features/saved-location/saved-location-settings/	CRUD list in settings page
location-picker-dialog	src/app/features/saved-location/location-picker-dialog/	Assign location to task (dropdown + "Use current location")

6.2 Modified Components

Component	Change
Task detail panel	Add "Location" field showing assigned location
Task schedule dialog	Add location option alongside time-based reminder
Settings page	Add "Locations" section
Reminder dialog	Show location name when triggered by geofence

6.3 Location Picker UX

┌─────────────────────────────────┐
│  Set Location Reminder          │
├─────────────────────────────────┤
│                                 │
│  📍 Use Current Location        │  ← gets GPS, prompts for label
│                                 │
│  ─── Saved Locations ────────── │
│                                 │
│  🏠 Home                        │
│  🏢 Office                      │
│  🛒 Grocery Store               │
│                                 │
│  [ Remove Location ] [ Cancel ] │
└─────────────────────────────────┘

6.4 Settings Section

┌─────────────────────────────────┐
│  Location Reminders             │
├─────────────────────────────────┤
│  [Toggle] Enable location       │
│          reminders              │
│                                 │
│  Saved Locations:               │
│  ┌─────────────────────────┐    │
│  │ 🏠 Home     200m  [✏️][🗑]│    │
│  │ 🏢 Office   150m  [✏️][🗑]│    │
│  │ 🛒 Grocery  200m  [✏️][🗑]│    │
│  └─────────────────────────┘    │
│  [ + Add Location ]            │
└─────────────────────────────────┘

---

7. Cross-Platform Behavior

Platform	Geofencing	Location Display	Notifications
Android	Native GeofencingClient, up to 100 fences, background	Yes	Native via BroadcastReceiver
iOS	Native CLLocationManager, up to 20 regions, background	Yes	Native via LocalNotifications
Electron	None	Yes (label only)	None
Web	None	Yes (label only)	None

---

8. File Structure

src/app/features/saved-location/
├── saved-location.model.ts
├── saved-location.const.ts                    # DEFAULT_RADIUS = 200
├── saved-location.service.ts
├── geofence.service.ts                        # Capacitor geofencing bridge
├── store/
│   ├── saved-location.actions.ts
│   ├── saved-location.reducer.ts
│   └── saved-location.selectors.ts
├── saved-location-settings/
│   ├── saved-location-settings.component.ts
│   └── saved-location-settings.component.html
└── location-picker-dialog/
    ├── location-picker-dialog.component.ts
    └── location-picker-dialog.component.html

src/app/root-store/meta/task-shared-meta-reducers/
└── saved-location-shared.reducer.ts           # Cascading delete

android/app/src/main/java/.../
└── GeofencePlugin.kt                         # Native Android geofencing
    GeofenceBroadcastReceiver.kt              # Handles fence enter events

ios/App/App/
└── GeofencePlugin.swift                      # Native iOS geofencing

---

9. All Files to Touch

New Files

File	Purpose
src/app/features/saved-location/saved-location.model.ts	Entity interface
src/app/features/saved-location/saved-location.const.ts	Defaults
src/app/features/saved-location/saved-location.service.ts	Service
src/app/features/saved-location/geofence.service.ts	Capacitor bridge
src/app/features/saved-location/store/saved-location.actions.ts	Actions
src/app/features/saved-location/store/saved-location.reducer.ts	Reducer + adapter
src/app/features/saved-location/store/saved-location.selectors.ts	Selectors
src/app/features/saved-location/saved-location-settings/*	Settings UI
src/app/features/saved-location/location-picker-dialog/*	Picker dialog
src/app/root-store/meta/task-shared-meta-reducers/saved-location-shared.reducer.ts	Cascading deletes
android/.../GeofencePlugin.kt	Android native geofencing
android/.../GeofenceBroadcastReceiver.kt	Android fence event handler
ios/App/App/GeofencePlugin.swift	iOS native geofencing

Modified Files

File	Change
packages/shared-schema/src/entity-types.ts	Add 'SAVED_LOCATION'
src/app/op-log/core/action-types.enum.ts	Add SAVED_LOCATION_ADD/UPDATE/DELETE
src/app/op-log/core/entity-registry.ts	Add SAVED_LOCATION config
src/app/op-log/model/model-config.ts	Add to AllModelConfig + MODEL_CONFIGS
src/app/root-store/root-state.ts	Add to RootState
src/app/root-store/feature-stores.module.ts	Register feature store
src/app/root-store/meta/meta-reducer-registry.ts	Register cascading delete in Phase 5
src/app/features/tasks/task.model.ts	Add locationReminderId field
src/app/features/config/global-config.model.ts	Add isLocationRemindersEnabled
src/app/features/config/default-global-config.const.ts	Set default false
src/app/core/platform/platform-capabilities.model.ts	Add geofencing capability
src/app/features/reminder/reminder.service.ts	Add locationReminders$ subject
src/app/features/reminder/reminder.module.ts	Merge location reminders into dialog flow
android/app/src/main/AndroidManifest.xml	Add location permissions
android/.../CapacitorMainActivity.kt	Register GeofencePlugin

---

10. Future Enhancements (Out of Scope)

• Map picker with OpenStreetMap tiles
• Address search / geocoding (Nominatim)
• Leave triggers ("remind when I leave the office")
• Time + location combos ("at the store, but only after 5 PM")
• Project default locations
• Location-based task views ("show tasks for where I am now")
• WiFi-based triggers (alternative to GPS, works indoors)
• Bluetooth beacon triggers

---

11. Verification Plan

1. Unit tests: SavedLocation reducer, selectors, service, cascading delete meta-reducer
2. Manual mobile testing:
   • Create location from "Use current location"
   • Assign to a task, verify geofence registration
   • Move in/out of geofence, verify notification fires
   • Complete task, verify geofence unregistered
   • Delete location, verify locationReminderId cleared on tasks
3. Desktop/web: Verify location label displays on tasks, no geofencing attempted
4. Sync: Create location on device A, verify it appears on device B
5. Lint/format: npm run lint, npm run prettier, npm test