cairnquire/.project/milestones/milestone-04-collaboration.md

Milestone 4: Collaboration Features

Duration: 2 weeks
Goal: Comments, notifications, email integration, and conflict resolution

Tasks

Week 7: Comments & Notifications

• Comment system (backend + UI wired)

  • Comment creation endpoint (web)
  • Comment threading (parent/child) - schema supports it
  • Line/section anchoring (hash-based)
  • Comment resolution (mark as resolved)
  • Comment display in the Go-served browser UI (c39c50b dropdown menu + comment side panel, comments.js +330 lines)

• Notification system (backend complete)

  • Notification queue in database
  • Per-file watcher subscriptions
  • Per-folder watcher subscriptions
  • Global notification settings
  • Digest mode (hourly/daily batches)

• Web notification UI (backend complete, JS partial)

  • Notification bell with unread count - API exists
  • Notification list dropdown - API exists
  • Mark as read functionality - API exists
  • Notification preferences page

Week 8: Email Integration & Conflict Resolution

• Postmark integration

  • SMTP sender stub (NoOp + SMTP implementations)
  • Postmark adapter (email/postmark.go)
  • Plain-text email templates (email/templates.go)
  • Outgoing email queue with retry (email/queue.go + migration 000016)
  • Webhook endpoint for inbound email

• Email notification types

  • File changed notification
  • New comment notification
  • Mention notification (@username) — template exists, mention detection not wired
  • Conflict alert notification — template exists, not triggered from sync flow
  • Digest summary email

• Email reply handling

  • Parse inbound email (from, subject, body)
  • Match to comment thread via In-Reply-To
  • Create comment from email body
  • Validate sender permission

• Conflict resolution UI (M2 - exists in sync flow)

  • Side-by-side diff view
  • Accept local/server/merge options
  • Manual merge editor
  • Conflict notification email

Acceptance Criteria

Functional

• Users can add comments to specific lines in a document (API exists)
• Comments are linked to document version (hash)
• Comment threading works (reply to reply) (schema supports it)
• Users can watch files or folders for changes (API exists)
• Email notifications sent within 1 minute of event (Postmark adapter + queue with retry)
• Replying to notification email creates a comment
• Digest emails batch notifications by time window
• Conflicts display side-by-side diff (M2 sync)
• Users can resolve conflicts via web UI (M2 sync)
• Resolved comments are hidden but accessible in history

Non-Functional

• Emails are plain-text only (no HTML) — enforced by templates, verified by test
• Email threading works in Gmail, Outlook, Apple Mail
• Webhook signature verified for inbound email
• Failed emails retried 3 times with exponential backoff — queue.go, verified by test
• Email queue doesn't block web requests (async processing) — worker runs in goroutine

Email Template Examples

File Change Notification:

Subject: [docs/api-reference.md] Updated by Alice

Alice updated "API Reference" at 2024-01-15 14:30 UTC.

Changed sections:
- Authentication
- Rate Limiting

View changes: https://example.com/docs/api-reference?v=abc123
Unsubscribe: https://example.com/unsubscribe/123

Comment Notification:

Subject: [docs/getting-started.md] Comment from Bob

Bob commented on "Getting Started":

> This step is unclear. Can we add an example?

Reply to this email to respond.

View online: https://example.com/docs/getting-started#comment-456

Database Schema Additions

-- Comments
CREATE TABLE comments (
    id TEXT PRIMARY KEY,
    document_id TEXT NOT NULL REFERENCES documents(id),
    version_hash TEXT NOT NULL,
    parent_id TEXT REFERENCES comments(id),
    author_id TEXT NOT NULL REFERENCES users(id),
    content TEXT NOT NULL,
    anchor_line INTEGER, -- line number for anchoring
    anchor_hash TEXT, -- hash of specific content for anchoring
    created_at DATETIME NOT NULL,
    resolved_at DATETIME,
    resolved_by TEXT REFERENCES users(id)
);

-- Notifications
CREATE TABLE notifications (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES users(id),
    type TEXT NOT NULL, -- file_changed, comment, mention, conflict
    resource_type TEXT NOT NULL,
    resource_id TEXT NOT NULL,
    message TEXT NOT NULL,
    read_at DATETIME,
    emailed_at DATETIME,
    created_at DATETIME NOT NULL
);

-- Watcher subscriptions
CREATE TABLE watchers (
    user_id TEXT REFERENCES users(id),
    document_id TEXT REFERENCES documents(id),
    folder_path TEXT,
    created_at DATETIME NOT NULL,
    PRIMARY KEY (user_id, document_id, folder_path)
);

Deliverables

1. Email template documentation
2. Webhook integration guide
3. Comment API documentation
4. Conflict resolution flow diagrams

Risk Mitigation

Risk	Mitigation
Email deliverability issues	Postmark reputation monitoring, SPF/DKIM setup
Comment spam	Rate limiting, auth required, moderation tools
Email parsing errors	Robust parser, fallback to plain text extraction
Conflict resolution UI confusion	Clear visual design, undo option, help text

Definition of Done

• All acceptance criteria pass
• Email flows tested with real Postmark account
• Comment threading tested with 3+ levels
• Conflict resolution tested with 2+ concurrent editors
• Notification preferences persist across sessions
• Digest mode tested with 24-hour window