# 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 the Go-served browser 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

```sql
-- 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