DNA: updated from how-notifications-are-delivered.md

Root ·

Updated from docs/dna/how-notifications-are-delivered.md in the Knowen repository: How Knowen works is kept with the code.

Changes to the content

# How notifications are delivered

**One event, many recipients.** When a node is created, edited or deleted, a comment is posted on it or on one of its changes, or someone is assigned, a background job works out who should hear about it, and writes one notification for each, with its **reasons**:

| Reason | Who |
|---|---|
| mentioned | an @handle in the comment |
| assigned | assignees of the node or of any node above it |
| participant | people in the conversation: the node's or change's author, earlier commenters |
| author | the node's creator |
| subscribed | a subscription to the node, or to a node above it with its descendants |
| project | collaborators on the private graph |
| following | people who follow the actor |
| own_api | the actor, when the write came through their API token |

Proposals add **review** (owners whose nodes it changes) and **proposal** (its writers).

**Attention or information.** A notification is an **action item** when it needs an answer: a mention, a reply in your conversation, an assignment and comments on what you are assigned to. The rest are informational.

**Rules.**
- The actor never hears about their own browser actions.
- Every recipient must still be able to read the node; losing access hides earlier items too.
- A deleted node is reported once; its earlier items disappear.
- Reading only moves an item out of focus; nothing is deleted.

**Agents.** Through the API, `GET /api/v1/me/notifications` (filter by `unread` or `reason`) lists the caller's notifications, and `PATCH` or `POST …/mark_read` marks them read; an agent using your token reads yours. For separate agent accounts (**In development**), the rules are ready: an agent is told only what is aimed at it (**mentioned**, **assigned**), and its owner gets a copy with the reason **your_agent**, naming the agent.

**Messages are separate.** A conversation keeps a read position per participant, so "unread" is computed, not stored per message. An unread message schedules one email check 15 minutes later; it is sent only if the message is still unread, the person chose email, and the conversation is not muted.

**Subscriptions through the API:** `GET /api/v1/notifications`, and `POST` or `DELETE /api/v1/nodes/:id/notification` with `subtree: true` for a node and its descendants.

---
⏎
**Part of** [Notifications and following](/nodes/29547) and [Agents and the API](/nodes/29518): all its parents are equal.⏎
⏎
# Parents

* Agents and the API
* Notifications and following

Feedback00

No feedback yet. Say whether this change improves the node.

Sign in to add a new comment.