# Milestone 4: Collaboration Features

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

## Tasks

### Week 7: Comments & Notifications

- [x] Comment system (backend complete, UI partial)
  - [x] Comment creation endpoint (web)
  - [x] Comment threading (parent/child) - schema supports it
  - [x] Line/section anchoring (hash-based)
  - [x] Comment resolution (mark as resolved)
  - [ ] Comment display in the Go-served browser UI (JS exists but needs wiring)
   
- [x] Notification system (backend complete)
  - [x] Notification queue in database
  - [x] Per-file watcher subscriptions
  - [x] Per-folder watcher subscriptions
  - [ ] Global notification settings
  - [ ] Digest mode (hourly/daily batches)
   
- [x] Web notification UI (backend complete, JS partial)
  - [x] Notification bell with unread count - API exists
  - [x] Notification list dropdown - API exists
  - [x] Mark as read functionality - API exists
  - [ ] Notification preferences page

### Week 8: Email Integration & Conflict Resolution

- [ ] Postmark integration
  - [x] SMTP sender stub (NoOp + SMTP implementations)
  - [ ] Postmark adapter
  - [ ] 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
   
- [x] Conflict resolution UI (M2 - exists in sync flow)
  - [x] Side-by-side diff view
  - [x] Accept local/server/merge options
  - [x] Manual merge editor
  - [ ] Conflict notification email

## Acceptance Criteria

### Functional
- [x] Users can add comments to specific lines in a document (API exists)
- [x] Comments are linked to document version (hash)
- [x] Comment threading works (reply to reply) (schema supports it)
- [x] Users can watch files or folders for changes (API exists)
- [ ] Email notifications sent within 1 minute of event (NoOp sender currently)
- [ ] Replying to notification email creates a comment
- [ ] Digest emails batch notifications by time window
- [x] Conflicts display side-by-side diff (M2 sync)
- [x] 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)
- [ ] 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