[WEB-5346]: refactor notifications to separate modules based on entities

[pablohashescobar]

Description

• removed the bulky notification task
• created a base notification handler to handle all the common functionality
• created work item notification handle to handle work item specific notifications

Type of Change

• [x] Code refactoring

Test Scenarios

• test all the work item notifications both in app and email

References

WEB-5346

Summary by CodeRabbit

• Refactor

  • Modernized the notification system architecture with a cleaner, more maintainable processing pipeline for issue and epic updates.
  • Consolidated notification logic into a centralized handler framework, improving code organization and reducing technical debt.

• Bug Fixes

  • Enhanced error handling and logging for notification processing to improve system reliability.

[makeplane[bot]]

Linked to Plane Work Item(s)

• [WEB-5346] Refactor notifications module to better handle all entities

This comment was auto-generated by Plane

[coderabbitai[bot]]

Walkthrough

The changes introduce a refactored notification system that replaces a legacy, multi-branch notification pipeline with a centralized, handler-based architecture. A new process_issue_notifications Celery task replaces the old notification task, delegating to pluggable IssueNotificationHandler and NotificationContext classes. The issue_activity_task now passes activities to the new task with updated parameter structures.

Changes

Cohort / File(s)	Summary
Notification Task Entry Point apps/api/plane/bgtasks/issue_activities_task.py	Updated to call new process_issue_notifications instead of notifications.delay, passing activities_data and actor_id with modified payload structure.
Core Notification Task apps/api/plane/bgtasks/notification_task.py	Introduced new process_issue_notifications Celery task that simplifies the notification pipeline by delegating to IssueNotificationHandler. Replaced legacy HTML parsing and bulk ORM operations with a centralized handler pattern. Returns structured dict with success status and notification counts.
Notification Framework Base apps/api/plane/utils/notifications/base.py	Defines new dataclasses (ActivityData, NotificationContext, NotificationPayload, MentionData, SubscriberData) and abstract BaseNotificationHandler class providing a pluggable, multi-step orchestration pipeline: entity/project/workspace/actor loading, activity parsing, mention processing, and in-app/email notification persistence.
Notification Framework Initialization apps/api/plane/utils/notifications/__init__.py	New package initializer re-exporting NotificationContext and WorkItemNotificationHandler as public API.
Issue/Epic Notification Handler apps/api/plane/utils/notifications/workitem.py	Concrete WorkItemNotificationHandler implementing issue/epic-specific notification logic: entity loading, subscriber management, mention extraction/updating, email preference evaluation, and tailored notification/email payload construction.

Sequence Diagram(s)

sequenceDiagram
    participant IssueActivityTask as issue_activities_task
    participant NotificationTask as process_issue_notifications<br/>(Celery Task)
    participant IssueHandler as IssueNotificationHandler
    participant DBModels as DB Models<br/>(Issue, Notification, etc.)
    
    IssueActivityTask->>NotificationTask: Call with activities_data,<br/>actor_id, etc.
    Note over NotificationTask: Create NotificationContext<br/>from arguments
    NotificationTask->>IssueHandler: Instantiate with context
    IssueHandler->>DBModels: load_entity, load_project,<br/>load_workspace, load_actor
    IssueHandler->>IssueHandler: parse_activities +<br/>normalize_activity_data
    IssueHandler->>IssueHandler: get_subscribers +<br/>process_entity_mentions
    IssueHandler->>DBModels: create_in_app_notification,<br/>create_email_notification
    IssueHandler->>NotificationTask: Return NotificationPayload
    NotificationTask->>NotificationTask: Extract notification counts
    NotificationTask->>IssueActivityTask: Return success dict with counts

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• Architectural refactor with new abstraction layer: The introduction of BaseNotificationHandler with multiple abstract methods and the full implementation in WorkItemNotificationHandler requires careful verification of the notification pipeline logic and extensibility assumptions.
• Data structure changes: Four new dataclasses (ActivityData, NotificationContext, NotificationPayload, SubscriberData) define the contract between components; verify schema completeness and backward compatibility.
• Delegation of complex logic: The process() method in BaseNotificationHandler orchestrates many steps (entity loading, activity parsing, subscriber/mention processing, notification persistence); trace the full flow to ensure correctness.
• Task signature and return semantics changes: process_issue_notifications changes return type from void to a dict with status/counts; verify all callers handle the new return value appropriately.
• Mention and subscriber handling: Multiple methods handle mention extraction, creation, and updating across entities; cross-check mention processing logic in both description and comment contexts.

Poem

🐰 Hop hop, the notifications now flow clear,
Through handlers grand, the path is near!
From tangled pipes to structures neat,
New dataclasses make it sweet—
Activities dance, subscribers cheer,
Our refactored gifts are here! 🌟

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main refactoring change: separating notifications into modules based on entities.
Description check	✅ Passed	The description covers key changes and includes type of change and test scenarios, but lacks detailed explanation of the architectural benefits and specific implementation details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch refactor-notifications

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}