03 — User Journeys (Communication Module)

1. Author journey: Draft → Publish → Measure (Aisha, Daniel)
2. Recipient journey: Feed → Detail → Read (Zainab)
3. Manager journey: Read-receipt audit (Aisha)
4. Chatter journey: 1:1/group messaging (Samuel)
5. Error / exception paths

End-to-end journeys mapped to backend flow. Backend behavior cited with file:line.

1. Author journey: Draft → Publish → Measure (Aisha, Daniel)

Step	Action	Backend call	Backend behavior
1	Open composer	—	local form state (draft is client-side only)
2	Title, body, audience	—	validated per `CreateAnnouncementDto`
(`create-announcement.dto.ts:29-49`)
3	Save draft	`POST /announcements`	creates doc with `published: false` and
`createdBy` from tenant context (`announcement.service.ts:31-37`); emits
`AnnouncementCreated` (`:39-51`)
4	Publish	`POST /announcements/:id/publish`	idempotent — returns early if already
published (`announcement.service.ts:68-70`); resolves audience → `targetUserIds`
(`:73-75,109-148`); sets `published: true`, `publishedAt` (`:76-78`); emits
`AnnouncementPublished` (`:80-91`)
5	Monitor	`GET /announcements/:id/reads`	returns `readBy[]` receipts
(`announcement.service.ts:104-107`)
6	Follow up	manual (no reminder automation)	—

Pain points: AudienceType.ALL resolves to [] (announcement.service.ts:144-146) — broadcast-all currently carries no resolved targets; unread-laggard export is a gap; expiry/priority (planned).

2. Recipient journey: Feed → Detail → Read (Zainab)

Step	Action	Backend call	Backend behavior
1	Open feed	`GET /announcements`	list, `sort: { createdAt: -1 }`
(`announcement.service.ts:56-60`); optional `?audience=` filter
2	Client-side "For me"	—	must match `targetUserIds` against own id locally;
`ALL`-type entries are always "for me" `(forward-looking)` — backend does not filter
(`announcement.service.ts:56-60`)
3	Open detail	`GET /announcements/:id` — gap: no route; reuse list item payload
`(forward-looking)`	—
4	Read + acknowledge	`POST /announcements/:id/read`	`$addToSet` receipt
`{userId, readAt}` — idempotent (`announcement.repository.ts:20-33`)
5	Check attachment	—	`attachments: string[]` stored on doc
(`create-announcement.dto.ts:45-49`)

3. Manager journey: Read-receipt audit (Aisha)

Open "My announcements" (list) → pick one → receipt breakdown: total targeted (targetUserIds.length), read count (readBy.length), unread (targetUserIds − readBy.userId). All derivable from GET /announcements/:id/reads
- targetUserIds from list payload.
Note: reads returns receipts but not the target list; client needs both (announcement.service.ts:104-107).

4. Chatter journey: 1:1/group messaging (Samuel)

Threads list → open thread (GET /threads, GET /threads/:id) → send (POST /messages); realtime delivery via WebSocket (planned), docs/IMPLEMENTATION_PLAN.md:119. (Messages are secondary surface in this package; see 04_Information_Architecture.md.)

5. Error / exception paths

Situation	Backend behavior	Client handling
Publish nonexistent id	`NotFoundException` `announcement.service.ts:64`	error snackbar
Mark read nonexistent id	`NotFoundException` `announcement.service.ts:100`	toast, refresh list
Audience name typo (grade/section)	resolves `[]` targets silently
(`announcement.service.ts:122,129`)	composer warns "0 recipients"
`(planned)` — backend does not validate
Duplicate read tap	`$addToSet` no-op (`announcement.repository.ts:27-31`)	idempotent UI