Announcements Domain - Workflow Narrative

A conversational guide to understanding internal communication workflows

What is the Announcements Domain?

Every organization needs internal communication. Policy changes, schedule announcements, emergency notifications, birthday wishes - these don't fit into patient records but are essential for running a practice.

The Announcements domain provides a social-media-style communication platform for staff. Post announcements, track who's seen them, allow comments and reactions - all within the organization context.

Announcements Overview

What An Announcement Contains

An announcement includes:

title - Headline of the announcement
content - The message body (text and formatting)
priority - normal, high, or urgent
author - Who posted it (user_id)
status - draft, published, archived
organization_id - Which organization (or null for global)

Visibility Scope

Announcements can be:

Organization-specific - Only visible to one organization
Global - Visible to all organizations (system announcements)

Global announcements are typically created by super-admins for platform-wide communications.

Creating Announcements

The Creation Flow

When staff creates an announcement via POST /announcements:

Validate the content (title required, content within limits)
Set the author to the current user
Set the organization_id from context
Default status to "draft" unless published immediately
Create the Announcement record

Publishing

An announcement in "draft" status is only visible to the author. When ready, it's published by updating status to "published".

Publishing makes it visible to all organization members (or all users for global announcements).

Priority Levels

normal - Regular announcement, appears in feed
high - Highlighted in feed, shown more prominently
urgent - Triggers immediate notifications to all users

Urgent Announcements and Notifications

Special Handling for Urgent

When an announcement with priority "urgent" is created (or updated to urgent), special notification logic kicks in.

The AnnouncementNotificationService handles:

Identify all active users in the organization
Create an activity event with type ANNOUNCEMENT_URGENT
Send push notifications to all users
This bypasses normal notification preferences

Use Case

Urgent announcements are for emergencies:

"Server maintenance in 10 minutes"
"Emergency staff meeting now"
"Critical policy update - read immediately"

Everyone gets notified regardless of their quiet hours or preference settings.

The Announcement Feed

Listing Announcements

list_announcements() returns the feed:

Fetch published announcements for the organization
Include global announcements
Order by post date (newest first)
Include read status for the requesting user
Include comment count for each

Read Status Integration

The response includes whether the current user has read each announcement. This powers "unread" badges and filtering.

Filtering Options

status - Only published, only drafts (for authors)
priority - Only high priority
unread_only - Only announcements user hasn't seen

Read Tracking

How Reads Are Recorded

When a user views an announcement, _mark_as_read() creates or updates an AnnouncementRead record:

announcement_id - Which announcement
user_id - Who read it
read_at - When they read it

Auto-Mark on View

By default, viewing an announcement marks it as read. The get_announcement_by_id() method does this automatically (can be disabled with auto_mark_read=False).

Who's Seen This?

For important announcements, authors might want to know who's read it. get_readers() returns a list of users who have read the announcement, with timestamps.

This is useful for:

Confirming policy acknowledgment
Tracking communication effectiveness
Following up with those who haven't read

Unread Count

The dashboard might show "3 unread announcements". get_unread_count() efficiently counts announcements the user hasn't seen.

Comments

Discussion Feature

Announcements support comments for discussion. Staff can ask questions, provide feedback, or discuss the announcement content.

Comment Structure

announcement_id - Which announcement
user_id - Who commented
content - The comment text
parent_comment_id - For replies (single-level nesting)
is_deleted - Soft delete flag

Creating Comments

create_comment() adds a comment:

Validate the announcement exists and is accessible
Validate content length
If replying, validate parent comment exists
Create the comment record

Reply Notifications

When someone replies to your comment, you get notified. The ANNOUNCEMENT_COMMENT_REPLY event triggers a push notification to the parent comment author.

This encourages engagement - you know when someone responds to your contribution.

Listing Comments

list_comments() returns comments for an announcement:

Ordered chronologically (oldest or newest first)
Includes author details
Includes reply relationships
Excludes deleted comments (or shows "[deleted]" placeholder)

Editing and Deleting Comments

Users can edit their own comments. Admins can edit any comment.

Deletion is soft - the record remains but is_deleted becomes true. The comment might show as "[Comment deleted]" to preserve thread integrity.

Reactions

Emoji Reactions

Like social media, announcements support emoji reactions. Users can react with thumbs up, heart, celebration, etc.

How Reactions Work

Reactions are stored in the announcement's content_json field:

{
  "reactions": {
    "👍": ["user_id_1", "user_id_2"],
    "❤️": ["user_id_3"],
    "🎉": ["user_id_1", "user_id_3"]
  }
}

One Reaction Per User

Each user can have only one reaction per announcement:

If user has no reaction: adds the new emoji
If user has a different reaction: replaces with new emoji
If user has the same reaction: toggles (removes) it

Reaction Counts

The UI shows aggregated counts: "👍 5 ❤️ 3 🎉 2"

get_reactions() returns counts and indicates which emoji the current user has selected.

Announcement Lifecycle

Status Flow

draft - Author is composing, not visible to others
published - Live and visible to organization
archived - Hidden from feed but preserved for history

Archiving vs Deleting

When you "delete" an announcement, it's actually archived. The record remains for audit purposes, but it no longer appears in the feed.

True deletion would lose the read tracking and comment history.

Global Announcements

System-Wide Communication

Super-admins can create global announcements (organization_id = null). These appear in everyone's feed across all organizations.

Use Cases

Platform maintenance notices
New feature announcements
Terms of service updates
Holiday greetings

Access Control

Only super-admins can create global announcements. Regular organization admins can only post within their organization.

Integration with Activity Events

Activity Event Creation

Creating an announcement triggers an activity event. This means announcements appear in the activity feed alongside clinical events.

The event type ANNOUNCEMENT_CREATED shows who posted what and when.

Urgent Announcement Events

ANNOUNCEMENT_URGENT is a special event type that triggers immediate notifications as discussed earlier.

Key Takeaways

Internal communication - Staff-to-staff messaging
Priority levels - Normal, high, urgent with different behaviors
Read tracking - Know who's seen what
Comments for discussion - Allow replies and engagement
Reactions for quick feedback - Emoji responses
Urgent bypasses preferences - Everyone gets notified
Archive, don't delete - Preserve history

Next: Read about the Access Control Domain to understand security workflows

အသုံးပြုသူ လက်စွဲစာအုပ်

Guides