# Notifications
Source: https://docs.aden.space/docs/help/get-started/notifications

How Aden tells users what happened, in-app bell, email, and push, plus the team email inbox and social inbox for managing external conversations.
{/* Generated by `bun docs:publish` from docs/features/notifications.md: edit the spec, not this file. */}

## Mobile: where a notification opens [#mobile-where-a-notification-opens]

`apps/mobile/src/lib/notification-route.ts` is the one mapper for both the
in-app bell list and push taps (warm and cold start, via
`getLastNotificationResponseAsync`). It prefers `entityType` + `entityId`
(track, album, playlist, mix, demo, booking\_inquiry, todo, chat\_thread, goal,
milestone, session) and falls back to parsing the web `navigationPath`, so a
notification for a web-only screen still lands on the nearest mobile screen.
Both senders (web `createNotifications`, worker `createWorkerNotifications`)
put `entityType`, `entityId`, `navigationPath` and `type` in the push `data`.

## Mobile: the feed comes from the API, for the avatars [#mobile-the-feed-comes-from-the-api-for-the-avatars]

`GET /api/v1/user/notification-feed` returns the caller's latest 30
notifications with each actor's avatar resolved from `users.avatar_key` to a
presigned, image-resized URL (deduped per actor, not per row). The phone used
to read the `notifications` table straight from Supabase and render
`users.avatar_url`, which is stale or empty for most accounts, so every row
showed initials. Read state (`read_at`) is still written directly to Supabase
and realtime keeps the badge in step. A notification with no actor (a worker
wrote it) renders the type icon in the circle, not a "?".

## Web: avatars are resolved server-side too [#web-avatars-are-resolved-server-side-too]

The bell popover and `/app/inbox` had the same gap the phone did: nothing joined
the actor, so every row rendered the Aden placeholder.
`getNotificationsForUserQuery` now embeds
`actor:users!notifications_actor_id_fkey` and
`team:teams!notifications_team_id_fkey`, and both callers
(`getMyNotifications`, the inbox page) batch the keys through
`getCachedOptimizedUrls(..., 'small')`, one call per feed. A notification with
no actor (a worker or the system wrote it) falls back to the team's avatar and
name, then to "Aden". `avatar_url` stays a last-ditch fallback for a key that
did not resolve.

## Workers use the same fan-out [#workers-use-the-same-fan-out]

`workers/email-demo` (new demo, new booking request) and
`workers/goal-notifications` (goal outbox) write notifications through
`createWorkerNotifications` in `@aden/worker-config/notify`: in-app row plus
Expo push, gated by `notification_preferences`. Goal kinds map to the
`goal_*` notification types in `packages/notifications/src/types.ts`. Neither
worker sends email; the templates live in the web app.

## What it is [#what-it-is]

Aden keeps you in the loop when something important happens in your team. Someone
leaves a comment mentioning you, a new track version is uploaded, or a collaborator
joins. Notifications arrive in the in-app bell, by email, or as a push message
(on your phone via the mobile app, or on your computer as a desktop
notification: enable it under Account → Notifications → "Notifications on this
device", works in Chrome, Edge and Firefox, and in Safari when Aden is added
to the Dock/home screen),
depending on your preferences.

Separately, your team can connect an email inbox (Gmail today) so that demo
submissions and other external emails land in Aden rather than a personal mailbox.
For organisations, a social inbox lets managers connect social platforms and reply
to messages without leaving Aden.

## Using it [#using-it]

### Staying on top of activity [#staying-on-top-of-activity]

Open the **notification bell** in the top navigation to see recent in-app
notifications: mentions, replies, invites, new versions, and more. Each item
links directly to the context it came from.

Unread notifications stand out (bolder text, a solid dot); read ones are dimmed.
You don't have to click a notification to clear it, **hovering** over an item
marks it as read, and the bell's unread count drops as you look through the list.
Prefer to clear everything at once? Hit **Seen all** to mark every notification
read in one go.

You're also told when your own access changes: if an admin removes you from a
team, re-adds you, or changes your role, or if someone removes you as a
collaborator on a track, album, mix, or playlist, or narrows/widens your access
scopes, that lands in your notification bell, so you always know why a team or
track stopped showing up on your dashboard.

### Adjusting what you receive [#adjusting-what-you-receive]

1. Go to **Account → Notifications** (`/app/account?page=notifications`).
2. Toggle channels on or off globally: email, in-app, or push.
3. Toggle individual event types: comment mentions, replies, track shares, etc.
4. To customise per team, open the same panel and switch to the **Per-team
   settings** tab. Each team can either inherit your account defaults or have its
   own overrides.

### Connecting a team email inbox [#connecting-a-team-email-inbox]

As a team owner or admin:

1. Go to **Integrations** in your team settings.
2. Choose **Email inbox** and click **Connect Gmail**.
3. Complete the OAuth flow. Aden stores only encrypted tokens.
4. Click **Sync** to pull recent emails in as demo submissions.
5. Review each fetched email and click **Accept** to create a demo, or dismiss it.

### Org social inbox (for organisations) [#org-social-inbox-for-organisations]

Organisation owners and admins can connect social platforms (Instagram DMs, etc.)
via **Settings → Integrations** in the org surface. Once connected, incoming
messages appear in the **Inbox** tab under Submissions. Reply directly from Aden.