cairnquire/docs/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

  • Comment creation endpoint (web)
  • Comment threading (parent/child)
  • Line/section anchoring (hash-based)
  • Comment resolution (mark as resolved)
  • Comment display in Preact UI

• Notification system

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

• Web notification UI

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

Week 8: Email Integration & Conflict Resolution

• Postmark integration

  • Go adapter setup
  • Plain-text email templates
  • Outgoing email queue with retry
  • Webhook endpoint for inbound email

• Email notification types

  • File changed notification
  • New comment notification
  • Mention notification (@username)
  • Conflict alert notification
  • 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

  • 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
• Comments are linked to document version (hash) [ ] Comment threading works (reply to reply)
• Users can watch files or folders for changes
• Email notifications sent within 1 minute of event
• Replying to notification email creates a comment
• Digest emails batch notifications by time window
• Conflicts display side-by-side diff
• Users can resolve conflicts via web UI
• Resolved comments are hidden but accessible in history

Non-Functional

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

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