01 — Product Overview (Communication Module)
- 1. Purpose
- 2. PRD / blueprint scope note (native-app exclusion)
- 3. Business goals
- 4. User goals
- 5. Why this exists
- 6. Module status matrix
- 7. Platform dependencies (backend)
- 8. Out of scope for this package
StudyLyon — Multi-Tenant ERP & School Management Platform. This package specifies the client-side (Flutter) design for the Communication module against the existing NestJS backend (
src/modules/communication/). Backend is the source of truth for routes, contracts, and behavior; shared foundations live in00-shared/.
1. Purpose
The Communication module lets an institution broadcast announcements to a chosen audience and run lightweight 1:1/group messaging (threads + messages). Announcements are the primary surface: admin/staff compose, publish, and measure read receipts; recipients (students, parents, teachers, staff) read them in a feed.
Backend scope today (docs/IMPLEMENTATION_PLAN.md:85-102, Phase 2): controllers
announcements, messages, threads; schemas announcement, message, thread; plus
events and repositories.
2. PRD / blueprint scope note (native-app exclusion)
The PRD blueprint (studylyon-blueprint/) targets a web dashboard; it defines no
native mobile client. There is no Communication/Announcements doc in
studylyon-blueprint/04-Modules/ — the nearest is Notifications.md, which scopes the
separate notification engine (notifications, notification_templates,
notification_preferences collections). The client docs in this package are therefore
written forward-looking: the Flutter app is not in the PRD and must be treated as a
design artifact, not a shipped scope. All mobile-only concerns (offline queue, push
delivery, local read-state caching) are marked (forward-looking).
3. Business goals
| Goal | Measure |
|---|---|
| Institutional broadcast in seconds | Draft → publish ≤ 3 taps from composer |
| Audience accuracy | No announcement delivered outside its audience |
| Delivery accountability | Read receipts per announcement, per recipient |
| Low operational noise | Recipients see only announcements targeted at them |
4. User goals
- Org Admin / Principal: publish institution-wide or targeted notices; see who has read them.
- Teacher / Staff: announce to one class/section or a role; follow up with laggards.
- Student / Parent: never miss a school notice in the feed; open + auto-acknowledge.
- Anyone: lightweight 1:1/group chat on threads.
5. Why this exists
Schools still run physical notice boards and ad-hoc WhatsApp groups. Announcements
consolidate this into one tenant-isolated, auditable channel with targeting and read
tracking; threads replace informal group chat. Per docs/IMPLEMENTATION_PLAN.md:174,
announcements are also indexed by global search.
6. Module status matrix
| Capability | Status | Source |
|---|---|---|
| Create announcement (draft) | Implemented | announcements.controller.ts:23-27 |
| List (filter by audience) | Implemented | announcements.controller.ts:29-33 |
| Publish + broadcast | Implemented | announcements.controller.ts:35-39 |
| Mark read | Implemented | announcements.controller.ts:41-45 |
| Read receipts | Implemented | announcements.controller.ts:47-51 |
Detail GET /announcements/:id | Gap | no route |
| Update / delete / archive | Gap | no route |
| Priority / pinned / expiry | (planned) | not in announcement.schema.ts |
| Templates | (planned) | IMPLEMENTATION_PLAN.md:231 |
RBAC communication.* perms | Gap | absent from permissions.constants.ts |
| Event→queue routing | Gap | absent from event-queue-map.ts |
| WebSocket realtime | (planned) | IMPLEMENTATION_PLAN.md:119 |
7. Platform dependencies (backend)
- NestJS 11 strict TS, JWT auth (
JwtAuthGuard,communication.module.ts:24,43) - MongoDB
announcementscollection, tenant-scoped viaBaseRepository(announcement.schema.ts:31,57) - Cross-module reads:
GradeRepository,SectionRepository,StudentRepository,OrganizationMembermodel (announcement.service.ts:6-8,25-26) - Domain events via
EventBus(AnnouncementCreated/AnnouncementPublished,announcement.service.ts:39-51,80-91) — queue fan-out is not yet wired (event-queue-map.tshas no Announcement routes)
8. Out of scope for this package
Notification engine (channels, preferences, templates) — Notifications module;
broadcast templates — (planned); delivery push/email mechanics — handled by the
Notifications module consumers of the emitted events.