Skip to main content

Notifications

Status: Proposed 2026-09-24, worker stubbed in the API

Notifications carry the subsystem shape from The Trick Book almost unchanged, because it is the best-engineered part of that codebase: idempotency keys, TTL indexes, a receipts poller, and a soft-ask on the device. What is removed is any analytics attached to them.

What ships in v1​

KindTriggerTo
Event reminder24 hours and 2 hours before an event the member RSVP'd toAttendee
Event changed or cancelledOrganizer edits time, place, or cancelsAttendees
RSVP milestoneCount crosses 10, 25, 50, 100Organizer (count only)
Friend requestSomeone sends a requestRecipient
Friend acceptedRequest acceptedRequester
New messageMessage in a conversationParticipants, respecting quiet hours
Place approvedA member's submission is approvedSubmitter

Nothing marketing, nothing "we miss you", nothing triggered by inactivity.

Device flow​

  1. The app never asks for push permission on first launch. It asks in context: after the first RSVP ("want a reminder?") or the first message, with a 14-day cooldown if declined.
  2. On grant, the Expo push token is registered at POST /api/push-tokens with the platform.
  3. On logout or account deletion, the token is unregistered.
  4. Tapping a notification deep-links (scheme vegangrove) to the event, conversation, or request.

Server flow​

dead token

RSVP, message, edit

reminderPlanner (idempotencyKey)

scheduled_notifications

reminderSender worker (5 min tick)

Expo push API

receipts poller (15 min)

push_tokens.deadAt

  • Every scheduled notification has an idempotency key (event:<id>:reminder24h:user:<id>), so re-planning after an edit is safe.
  • Quiet hours are per member (default 22:00 to 08:00 local, from the device's timezone sent at registration as an offset, not a location). Messages during quiet hours are delivered silently.
  • Dead tokens (Expo receipt DeviceNotRegistered) are marked and purged after 30 days.

Data and visibility​

push_tokens, notification_preferences, scheduled_notifications. All self-visibility. Notification payloads contain a handle and an event title at most, never message text (the body says New message from <handle>).

API​

POST/DELETE /api/push-tokens, GET/PUT /api/me/notification-preferences.

Open questions​

  • Email fallback for members without push. Proposal: event reminders only, opt-in, M3.
  • Web push. Proposal: not in v1; the web app shows an in-app badge.