docs: add Notifications System comprehensive spec

[mostronatorcoder]

Summary

Documents the complete Notifications System (point 12 from the feature list) including in-app notification history, push delivery via FCM, server registration, and background handling.

New File: NOTIFICATIONS_SYSTEM.md

Comprehensive spec covering:

Architecture Components

1. Data Models

• NotificationModel — id, type, action, title, message, timestamp, isRead, orderId, data
• NotificationType enum with 7 categories:
  • orderUpdate, tradeUpdate, payment, dispute, cancellation, message, system
• Automatic Action → NotificationType mapping

2. Services Layer

• PushNotificationService

  • Registers device tokens with Mostro push server (plaintext HTTP in Phase 3)
  • Methods: initialize(), registerToken(), unregisterToken(), reRegisterAllTokens()
  • Tracks registered trade pubkeys for re-registration
  • Settings integration via isPushEnabledInSettings callback

• FCMService — Firebase Cloud Messaging integration (see FCM_IMPLEMENTATION.md)

• BackgroundNotificationService — Process notifications when app inactive

3. State Management

• NotificationsNotifier managing notification list + unread count
• NotificationsState — immutable state (list, unread, loading)
• Multiple providers: notificationsHistoryProvider, unreadCountProvider, temporaryNotificationsProvider

4. Persistence

• NotificationsHistoryRepository — local database (Sembast)
• Methods: addNotification(), markAsRead(), markAllAsRead(), deleteNotification(), deleteAll(), getAll(), getUnreadCount()

5. Utilities

• notification_message_mapper — Action + payload → localized title/message
• notification_data_extractor — Extract orderId, disputeId, deep-link data

NotificationsScreen (/notifications)

Features:

• Pull-to-refresh
• Actions menu (⋮): Mark all read, Delete all
• Bell icon with unread badge
• Empty state (bell-slash icon)
• Optional Backup Reminder card

NotificationItem Widget:

• Header: icon + title + relative timestamp
• Content: message + optional orderId display
• Footer: "Mark as read" button
• Tap → navigate to /trade_detail or /dispute_details
• Long-press → context menu

Push Notification Flow

Registration:

1. User creates/takes order → session with tradeKey
2. App calls pushService.registerToken(tradeKey.public)
3. POST to push server: {trade_pubkey, token, platform}
4. Server stores mapping: trade_pubkey → [device_tokens]
5. Mostro daemon sends NIP-59 gift wrap to trade_pubkey
6. Push server looks up tokens, sends FCM data message
7. FCM delivers silent push
8. App decrypts, creates NotificationModel, persists
9. UI updates via NotificationsNotifier

Token Refresh:

• FCM token changes → reRegisterAllTokens() for all active trades

Unregistration:

• User disables push → unregisterAllTokens() + deleteToken()

Security

Phase 3 (Current):

• Token registration: plaintext HTTP (HTTPS encrypted in transit)
• Push payload: silent data with encrypted NIP-59 gift wrap
• Decryption: client-side using trade key

Phase 5 (Planned):

• Token encryption: ECDH + ChaCha20-Poly1305
• Goal: push server cannot link tokens to trade identities

Updated Files

README.md

• Added NOTIFICATIONS_SYSTEM.md entry in Features section

NAVIGATION_ROUTES.md

• Linked /notifications route to spec
• Added Notifications System to cross-references table

Cross-References

All specs properly linked:

• FCM_IMPLEMENTATION.md
• NOTIFICATION_SETTINGS.md
• SETTINGS_SCREEN.md
• TRADE_EXECUTION.md
• NAVIGATION_ROUTES.md
• LOGGING_SYSTEM.md

No orphaned documents.

Summary by CodeRabbit

• Documentation
  • Added comprehensive notification system documentation covering architecture, features, and user interaction patterns.
  • Updated system references to link to the new notifications documentation.

[grunch]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a4ced7d3-d354-4094-becf-acc6121d66e6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This pull request introduces comprehensive documentation for the v1 notification system architecture, including persistent in-app history and FCM-based push delivery. The documentation is added as a new reference file with corresponding updates to navigation routes and the documentation index.

Changes

Cohort / File(s)	Summary
New Notification System Documentation .specify/v1-reference/NOTIFICATIONS_SYSTEM.md	Added 218-line reference document detailing dual-layer notification architecture: data models (types, categories, action mapping), services (FCM integration, token management, background handler), state management (Riverpod providers), persistence (CRUD operations, read/unread), utilities (payload mapping, deep-link extraction), screen behaviors (refresh, bulk actions, badges, empty states), interaction patterns, registration/token refresh flows, notification types with icons, and Phase 3/5 security notes.
Documentation Cross-References .specify/v1-reference/NAVIGATION_ROUTES.md, .specify/v1-reference/README.md	Updated /notifications route entry to reference NOTIFICATIONS_SYSTEM.md via parenthetical "see …" note; added "Notifications System" entry to Cross References table; indexed new documentation file in Document Index table.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: HOME & NAVIGATION specs #20: Updates to NAVIGATION_ROUTES.md share a direct file-level connection; this PR extends references within that navigation documentation file.

Poem

🐰 A whisker-twitch of joy, dear friend!
New docs from start to very end,
Notifications dance so bright,
FCM push through the night,
In-app history shines right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add Notifications System comprehensive spec' accurately and directly describes the main change—addition of a comprehensive specifications document for the Notifications System.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/notifications-system

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

.specify/v1-reference/README.md (1)

67-67: Tighten V2 relevance wording for notifications to match the migration section.

Line 67 may read as conflicting with the later note that notifications stay in Flutter. Consider narrowing this to: “FCM/platform handling in Flutter; event/domain mapping shared with Rust core (where applicable).”

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.specify/v1-reference/README.md at line 67, The table row for
NOTIFICATIONS_SYSTEM.md currently implies full notification handling in
Rust/Flutter; update the wording in that row (the table entry for
[NOTIFICATIONS_SYSTEM.md]) to the suggested tighter phrasing: “FCM/platform
handling in Flutter; event/domain mapping shared with Rust core (where
applicable).” Replace the existing cell content exactly with that sentence to
align with the migration note.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.specify/v1-reference/NOTIFICATIONS_SYSTEM.md:
- Line 40: Replace the inconsistent transport-security wording: locate the
phrase "**Purpose:** Register device tokens with Mostro push server (plaintext
HTTP in Phase 3)." and the other occurrence that says "encrypted in transit via
HTTPS" and change both to a single clear sentence such as "HTTPS transport with
plaintext registration fields" (or equivalent wording) so both references
consistently state that the connection is over HTTPS while the registration
payload fields are sent in plaintext.

---

Nitpick comments:
In @.specify/v1-reference/README.md:
- Line 67: The table row for NOTIFICATIONS_SYSTEM.md currently implies full
notification handling in Rust/Flutter; update the wording in that row (the table
entry for [NOTIFICATIONS_SYSTEM.md]) to the suggested tighter phrasing:
“FCM/platform handling in Flutter; event/domain mapping shared with Rust core
(where applicable).” Replace the existing cell content exactly with that
sentence to align with the migration note.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2c43f1b2-04ce-464a-9f78-77d7f9f967d4

📥 Commits

Reviewing files that changed from the base of the PR and between fd50582 and 524a965.

📒 Files selected for processing (3)

• .specify/v1-reference/NAVIGATION_ROUTES.md
• .specify/v1-reference/NOTIFICATIONS_SYSTEM.md
• .specify/v1-reference/README.md