Notifications

Beginner walkthrough

Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. Sign in as a test member and open Settings → Notifications to review the available channel preferences.

2. Use two test members in one workspace and trigger a local test event, such as an invite, with EMAIL_PROVIDER=local.

3. Confirm only eligible members and enabled channels receive a notification in the app or local outbox. Do not send test messages to real members.

For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.

• Before you start
• Terminal basics
• Web local setup
• Agent prompts & project memory

Use the product event pipeline

notification-events.ts maps billing, budget, invite, membership and connected-account events to localized copy and per-member delivery plans. The API and app clients read the signed-in workspace's notifications; preferences control eligible channels.

Some events intentionally stay in-app. Connected-account refresh failures, for example, must not expose token detail or trigger unsolicited email.

Respect recipient preferences

Use the existing delivery planner, default preferences and actor-exclusion options rather than independently sending a message to every member. Transactional email still uses the configured provider and records its own delivery outcome.

Verify recipients and state

Test a disabled preference, excluded actor, removed member, unread/read behavior and another workspace. Keep dynamic updates accessible and verify localized messages.

• Email delivery
• Notification dictionaries

Setup and configuration

The notification service (notification-service.ts) stores workspace-scoped in-app records; GET /api/notifications lists them for the signed-in member and the mark-read route updates state. Per-user preference flags gate categories such as product updates and security alerts.

Members manage preferences under /settings/notifications. Platform announcements are authored through announcement-actions and delivered through the same pipeline.

GET   /api/notifications
PATCH /api/notifications   (mark-read)

Emitted on mutations, e.g.:
  member.left
  member.role_changed

Implementation workflow

Emit a notification after a successful mutation — never before the write commits. Keep payloads structured (type, workspace, references) so the interface can render and route them without parsing prose.

Check the preference flag before delivering a category that can be disabled; security-relevant notices (new session, key changes) should remain mandatory.

Verification and troubleshooting

Verify a disabled preference suppresses delivery, mark-read persists across sessions, another workspace cannot list the records, and announcements reach intended members. Keep notification fan-out off the request's critical path where volume grows.