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

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;

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:

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

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

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

6.2 Modified Components

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

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

Modified Files

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