Announcements — Behavior

State machine

create (announcements row, deleted_at = null)
   ├── broadcast (WS event) — synchronous on create
   ├── push fan-out — fire-and-forget
   ├── email fan-out — only when the author chose an audience; one queued job per recipient
   ├── track event — fire-and-forget PostHog
   │
   ├── per-recipient: unread → markRead → read (announcement_reads row inserted)
   │
   └── (planned) archive — sets deleted_at; list filters out

Invariants

Golden paths

Coach broadcasts “Holiday hours”

1. Coach opens the create-announcement dialog, types title + content.
2. POST /announcements.
3. Service:
   • Inserts row.
   • Fetches author name, role, and getActiveMemberCount.
   • gateway.broadcastAnnouncement(orgId, response) → WS event announcement:new to org:{orgId} room.
   • fanOutAnnouncementPush(orgId, authorUserId, response) queries every active membership, drops the author, calls push.notifyUsers(recipientIds, payload) with category announcement.
   • EventTrackingService.track('announcement_published', {...}).
4. Returns the full AnnouncementResponse.

Coach chooses how to send

The dialog has two independent switches: App (on by default) and Email. At least one must be on; the API refuses a request with neither (400).

Coach attaches a file to the email

1. With Email on, the dialog offers one optional file. Allowed: PDF, images (jpg, png, webp, gif), Office files (doc, docx, xls, xlsx, ppt, pptx) and plain text. Limit: 5 MB (ANNOUNCEMENT_ATTACHMENT_MAX_BYTES).
2. The browser checks size and type first. A file over the limit is refused at once with “Add a link to the file in the message instead”, and nothing is uploaded. Send stays disabled until the file is removed.
3. A valid file uploads straight to R2 through POST /announcements/attachment/presign (staff only, same staged-upload flow as other uploads).
4. On send, the server checks the upload is the sender’s, is an announcement attachment, and is within the limit against the real object size, not the declared one. The attachment name always takes its extension from the verified type, so a file cannot go out as report.pdf.exe.
5. The server makes one download link (valid 24 hours) and puts it in every queued job. Resend downloads the file from that link when it sends. Our workers never read or hold the file, so a large send stays fast.
6. The file goes only with the email. It is not shown in the app, even when App is also on.

Coach emails the announcement

1. In the create dialog the coach switches on “Email”. The audience picker appears.
2. The audience is either everyone the filters match (search, role, member state, payment, account), minus any people the coach unticks, or picked people (exactly the ticked ones).
3. POST /announcements/email-preview (debounced, on every change) returns matched, eligible, optedOut and overLimit. The count comes from the server, so it is right however many rows the list has loaded. The list below the filters loads 50 members per page from GET /members with the same filters.
4. POST /announcements carries emailAudience. The service resolves the audience again (it never trusts the preview), publishes, then queues one announcement-email job per recipient.
5. AnnouncementEmailProcessor sends each email through EmailService with the org’s branding and the recipient’s locale. The idempotency key announcement:{id}:{userId} stops a retry from mailing someone twice.
6. The response carries emailQueued and emailFailed. A queue outage never fails the request: the announcement stays published and emailFailed is true.
7. One announcement.emailed audit row records the counts. It holds no addresses.

Member reads the announcement

1. Mobile/web fetches GET /announcements/unread-count for the bell badge.
2. User opens the bell → GET /announcements?limit=20 returns paginated list with per-member readAt.
3. User taps an item → PUT /announcements/:id/read upserts the read row.
4. Bell badge re-fetches.

Staff sees read receipts

1. Staff opens the announcement detail.
2. GET /announcements/:id returns title/content + read receipts list (member ID, read time).

Edge cases

Side effects

Permissions