Workflow

Notifications & The Author Verify Loop

When an AI agent or developer applies a comment, how does the author find out? And how do they confirm it actually looks right — or tell the team it isn't fixed?

Pointer answers these questions with In-App Notifications and the Author Verify Loop (Roadmap §10, R2-04). The entire loop happens right inside the widget, without requiring email services, third-party messaging integrations, or context switching.

Why In-App Only?

Pointer is intentionally designed around in-app feedback:

• No email spam: Stakeholders and clients are not inundated with emails for routine feedback triage.
• Zero third-party dependencies: Operates entirely through Pointer’s own backend database and lightweight polling, without SMTP servers, Twilio, or webhooks required.
• Contextual resolution: Reviewers verify the fix in the actual web app where the feedback was left, seeing the live styling and behavior in real time.

The Updates Badge & Menu

Whenever an event occurs on one of your comments, Pointer delivers an in-app notification to your account:

• CommentApplied: A developer or AI agent applied your comment and recorded a commit URL.
• CommentReopened: A comment was reopened (for instance, rejected during verification).
• ReplyAdded: Another teammate or an AI assistant replied to your comment.

Clicking the Updates button in the widget toolbar opens the notifications dropdown menu:

• Lists your recent notifications with timestamp, event type, and excerpt.
• Applied notifications provide direct links to the git commit SHA.
• Opening the dropdown automatically marks all unread notifications as read via POST /api/me/notifications/read-all, instantly clearing the badge.
• Clicking any notification item immediately switches to the comments sidebar, scrolls to the referenced comment, and highlights it with an animation.

The Author Verify Loop (👍 / 👎)

When an applied comment is viewed, its author sees inline verification controls next to the completed status pill:

1. Thumbs-Up: "Looks right"

If the change successfully resolves the issue:

• Clicking 👍 Looks right calls POST /api/comments/{id}/verify with { "ok": true }.
• The backend records a verified_at timestamp on the comment.
• An automated reply is logged: "Verified ✓".
• The card permanently displays a green ✓ Verified pill for all teammates to see.

2. Thumbs-Down: "Not fixed"

If the fix was incomplete, introduced a regression, or missed the requirement:

• Clicking 👎 Not fixed displays an inline note box prompting: "Explain what is still not fixed…"
• A note explaining the failure is strictly required (up to 500 characters).
• Submitting calls POST /api/comments/{id}/verify with { "ok": false, "note": "..." }.
• The backend resets the comment status back to Open and clears VerifiedAt.
• A new reply is appended to the discussion: "Not fixed: <note>".
• A CommentReopened notification is automatically dispatched to whoever applied the comment (e.g. the developer or AI runner), alerting them to revisit the task.

Tenancy & Security Invariants

The notifications and verification architecture strictly maintains Pointer's multi-tenant isolation:

• Recipient-scoped isolation: Notifications are strictly filtered to the authenticated caller (UserId == _currentUser.Id). Users within the same tenant cannot see or mark each other's notifications. Attempting to access another user's notification returns an immediate 404 Not Found.
• Cascade deletion: Deleting a comment automatically cascades to all associated notifications in PostgreSQL, preventing dangling references.
• Ownership validation: Only the comment's author or a workspace admin can invoke the verify endpoint. Unauthorized verify attempts return 403 Forbidden.