Add conflict resolution diff UI and app branding

2026-05-13 16:25:28 -04:00
parent 780ff3a02c
commit d359baa010
83 changed files with 4523 additions and 3735 deletions
--- a/.project/milestones/milestone-04-collaboration.md
+++ b/.project/milestones/milestone-04-collaboration.md
@@ -0,0 +1,171 @@
+# 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
+
+```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