diffdown-app / docs / plans / 2026-03-18-shared-documents.md

# Shared Documents Dashboard Section Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a "Documents Shared with You" section to the dashboard that lists documents the current user is a collaborator on.

**Architecture:** Collaborator relationships are stored as a `collaborators []string` (DIDs) array inside each document record on the owner's PDS. There is no central index of "documents I collaborate on" — we need to persist that mapping in the local SQLite DB when a collaborator accepts an invite. The dashboard then queries that local table to get the list of (ownerDID, rkey) pairs, fetches each document title from the owner's PDS via XRPC, and renders them alongside the user's own documents.

**Tech Stack:** Go 1.22, SQLite (WAL), ATProto XRPC client, `html/template`, gorilla/sessions

---

### Task 1: Add `collaborations` table via migration

**Files:**
- Create: `migrations/008_collaborations.sql`

**Step 1: Write the migration**

```sql
CREATE TABLE IF NOT EXISTS collaborations (
    collaborator_did TEXT NOT NULL,
    owner_did        TEXT NOT NULL,
    document_rkey    TEXT NOT NULL,
    added_at         DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (collaborator_did, owner_did, document_rkey)
);
```

**Step 2: Verify migration runs**

Start the server (`go run ./cmd/server`) and confirm in logs: `Applied migration: 008_collaborations.sql`. Stop server.

**Step 3: Commit**

```bash
git add migrations/008_collaborations.sql
git commit -m "Add collaborations table to track shared documents"
```

---

### Task 2: Add DB methods for collaborations

**Files:**
- Modify: `internal/db/db.go`

**Step 1: Write the failing test**

In `internal/db/db_test.go` (create if absent):

```go
func TestCollaborations(t *testing.T) {
    d := openTestDB(t)
    const collabDID = "did:plc:collab"
    const ownerDID  = "did:plc:owner"
    const rkey      = "abc123"

    if err := d.AddCollaboration(collabDID, ownerDID, rkey); err != nil {
        t.Fatalf("AddCollaboration: %v", err)
    }
    // idempotent
    if err := d.AddCollaboration(collabDID, ownerDID, rkey); err != nil {
        t.Fatalf("AddCollaboration (dup): %v", err)
    }

    rows, err := d.GetCollaborations(collabDID)
    if err != nil {
        t.Fatalf("GetCollaborations: %v", err)
    }
    if len(rows) != 1 {
        t.Fatalf("want 1 row, got %d", len(rows))
    }
    if rows[0].OwnerDID != ownerDID || rows[0].DocumentRKey != rkey {
        t.Errorf("unexpected row: %+v", rows[0])
    }
}
```

You'll need an `openTestDB` helper — look for one in the existing test files. If absent, create:

```go
func openTestDB(t *testing.T) *DB {
    t.Helper()
    dir := t.TempDir()
    SetMigrationsDir("../../migrations")
    d, err := Open(filepath.Join(dir, "test.db"))
    if err != nil {
        t.Fatal(err)
    }
    if err := d.Migrate(); err != nil {
        t.Fatal(err)
    }
    t.Cleanup(func() { d.Close() })
    return d
}
```

**Step 2: Run test to confirm it fails**

```bash
go test ./internal/db/... -run TestCollaborations -v
```

Expected: compile error — `AddCollaboration` and `GetCollaborations` undefined.

**Step 3: Add `CollaborationRow` type and DB methods to `internal/db/db.go`**

```go
type CollaborationRow struct {
    CollaboratorDID string
    OwnerDID        string
    DocumentRKey    string
    AddedAt         time.Time
}

func (db *DB) AddCollaboration(collabDID, ownerDID, rkey string) error {
    _, err := db.Exec(
        `INSERT INTO collaborations (collaborator_did, owner_did, document_rkey, added_at)
         VALUES (?, ?, ?, ?)
         ON CONFLICT DO NOTHING`,
        collabDID, ownerDID, rkey, time.Now(),
    )
    return err
}

func (db *DB) GetCollaborations(collabDID string) ([]CollaborationRow, error) {
    rows, err := db.Query(
        `SELECT collaborator_did, owner_did, document_rkey, added_at
         FROM collaborations WHERE collaborator_did = ? ORDER BY added_at DESC`,
        collabDID,
    )
    if err != nil {
        return nil, err
    }
    defer rows.Close()
    var result []CollaborationRow
    for rows.Next() {
        var r CollaborationRow
        if err := rows.Scan(&r.CollaboratorDID, &r.OwnerDID, &r.DocumentRKey, &r.AddedAt); err != nil {
            return nil, err
        }
        result = append(result, r)
    }
    return result, rows.Err()
}
```

**Step 4: Run test to confirm it passes**

```bash
go test ./internal/db/... -run TestCollaborations -v
```

Expected: PASS.

**Step 5: Commit**

```bash
git add internal/db/db.go internal/db/db_test.go
git commit -m "Add AddCollaboration and GetCollaborations DB methods"
```

---

### Task 3: Record collaboration on invite acceptance

**Files:**
- Modify: `internal/handler/handler.go` — `AcceptInvite` function (~line 586)

**Step 1: After `PutDocument` succeeds in `AcceptInvite`, insert the collaboration row**

Find the block:
```go
h.DB.DeleteInvite(invite.Token)
// Redirect to owner-scoped document URL...
http.Redirect(w, r, "/docs/"+invite.CreatedBy+"/"+rKey, http.StatusSeeOther)
```

Replace with:
```go
h.DB.DeleteInvite(invite.Token)

if err := h.DB.AddCollaboration(collabSession.DID, invite.CreatedBy, rKey); err != nil {
    log.Printf("AcceptInvite: record collaboration: %v", err)
    // Non-fatal: collaborator is already on the document; just redirect.
}

http.Redirect(w, r, "/docs/"+invite.CreatedBy+"/"+rKey, http.StatusSeeOther)
```

Also handle the "already a collaborator" early-return — add the same `AddCollaboration` call there (idempotent, safe to call again):

```go
for _, c := range doc.Collaborators {
    if c == collabSession.DID {
        h.DB.AddCollaboration(collabSession.DID, invite.CreatedBy, rKey) // ensure row exists
        http.Redirect(w, r, "/docs/"+invite.CreatedBy+"/"+rKey, http.StatusSeeOther)
        return
    }
}
```

**Step 2: Build**

```bash
go build ./...
```

Expected: no errors.

**Step 3: Commit**

```bash
git add internal/handler/handler.go
git commit -m "Record collaboration row when invite is accepted"
```

---

### Task 4: Fetch shared documents in the Dashboard handler

**Files:**
- Modify: `internal/handler/handler.go` — `Dashboard` function (~line 134)

**Step 1: Add `DashboardContent` struct to hold both document lists**

Near the top of `handler.go`, alongside `PageData` and `DocumentEditData`:

```go
type DashboardContent struct {
    OwnDocs    []*model.Document
    SharedDocs []*SharedDocument
}

type SharedDocument struct {
    RKey     string
    OwnerDID string
    Title    string
    UpdatedAt string
    CreatedAt string
}
```

**Step 2: Update `Dashboard` to populate both lists**

Replace the existing `Dashboard` handler body (after the user/client setup) with logic that:

1. Lists the user's own records (existing logic, unchanged).
2. Calls `h.DB.GetCollaborations(session.DID)` to get shared doc references.
3. For each collaboration row, uses `h.xrpcClient(ownerUser.ID)` to call `GetRecord` on the owner's PDS and extract title/dates.
4. Passes a `DashboardContent` as `Content`.

```go
func (h *Handler) Dashboard(w http.ResponseWriter, r *http.Request) {
    user, userHandle := h.currentUser(r)
    if user == nil {
        h.render(w, "landing.html", PageData{Title: "Diffdown"})
        return
    }

    empty := DashboardContent{OwnDocs: []*model.Document{}, SharedDocs: []*SharedDocument{}}

    client, err := h.xrpcClient(user.ID)
    if err != nil {
        log.Printf("Dashboard: xrpc client: %v", err)
        h.render(w, "documents.html", PageData{Title: "Documents", User: user, UserHandle: userHandle, Content: empty})
        return
    }

    // Own documents
    records, _, err := client.ListRecords(client.DID(), collectionDocument, 100, "")
    if err != nil {
        log.Printf("Dashboard: list records: %v", err)
        h.render(w, "documents.html", PageData{Title: "Documents", User: user, UserHandle: userHandle, Content: empty})
        return
    }
    var ownDocs []*model.Document
    for _, rec := range records {
        doc := &model.Document{}
        if err := json.Unmarshal(rec.Value, doc); err != nil {
            continue
        }
        doc.URI = rec.URI
        doc.CID = rec.CID
        doc.RKey = model.RKeyFromURI(rec.URI)
        ownDocs = append(ownDocs, doc)
    }

    // Shared documents
    session, _ := h.DB.GetATProtoSession(user.ID)
    var sharedDocs []*SharedDocument
    if session != nil {
        collabs, err := h.DB.GetCollaborations(session.DID)
        if err != nil {
            log.Printf("Dashboard: get collaborations: %v", err)
        }
        for _, c := range collabs {
            ownerUser, err := h.DB.GetUserByDID(c.OwnerDID)
            if err != nil {
                log.Printf("Dashboard: owner not found %s: %v", c.OwnerDID, err)
                continue
            }
            ownerClient, err := h.xrpcClient(ownerUser.ID)
            if err != nil {
                log.Printf("Dashboard: owner xrpc client %s: %v", c.OwnerDID, err)
                continue
            }
            value, _, err := ownerClient.GetRecord(c.OwnerDID, collectionDocument, c.DocumentRKey)
            if err != nil {
                log.Printf("Dashboard: get shared record %s/%s: %v", c.OwnerDID, c.DocumentRKey, err)
                continue
            }
            var doc model.Document
            if err := json.Unmarshal(value, &doc); err != nil {
                continue
            }
            sharedDocs = append(sharedDocs, &SharedDocument{
                RKey:      c.DocumentRKey,
                OwnerDID:  c.OwnerDID,
                Title:     doc.Title,
                UpdatedAt: doc.UpdatedAt,
                CreatedAt: doc.CreatedAt,
            })
        }
    }

    h.render(w, "documents.html", PageData{
        Title:      "Documents",
        User:       user,
        UserHandle: userHandle,
        Content:    DashboardContent{OwnDocs: ownDocs, SharedDocs: sharedDocs},
    })
}
```

**Step 3: Build**

```bash
go build ./...
```

Expected: no errors. (Template will need updating in the next task.)

**Step 4: Commit**

```bash
git add internal/handler/handler.go
git commit -m "Fetch shared documents for dashboard"
```

---

### Task 5: Update the documents template

**Files:**
- Modify: `templates/documents.html`

**Step 1: Update the template to use `DashboardContent`**

The template currently iterates over `.Content` directly. Change it to use `.Content.OwnDocs` and add a new section for `.Content.SharedDocs`. The shared doc link format is `/docs/{ownerDID}/{rkey}` (same as the collaborator view URL established in existing routes).

```html
{{template "base" .}}
{{define "content"}}
<div class="dashboard">
    <div class="dashboard-header">
        <h2>Your Documents</h2>
        <div style="display:flex;align-items:center;gap:1rem">
            <div class="view-toggle">
                <button id="btn-cards" title="Card view" onclick="setView('cards')">⊞</button>
                <button id="btn-list" title="List view" onclick="setView('list')">≡</button>
            </div>
            <a href="/docs/new" class="btn">New Document</a>
        </div>
    </div>
    <div class="repo-list" id="doc-list">
        {{range .Content.OwnDocs}}
        <a href="/docs/{{.RKey}}" class="repo-card">
            <h3>{{.Title}}</h3>
            {{if .UpdatedAt}}
            <time>Updated {{.UpdatedAt | fmtdate}}</time>
            {{else}}
            <time>Created {{.CreatedAt | fmtdate}}</time>
            {{end}}
        </a>
        {{else}}
        <div class="empty-state">
            <p>No documents yet.</p>
            <a href="/docs/new" class="btn">Create your first document</a>
        </div>
        {{end}}
    </div>

    {{if .Content.SharedDocs}}
    <div class="dashboard-header" style="margin-top:2rem">
        <h2>Documents Shared with You</h2>
    </div>
    <div class="repo-list" id="shared-list">
        {{range .Content.SharedDocs}}
        <a href="/docs/{{.OwnerDID}}/{{.RKey}}" class="repo-card">
            <h3>{{.Title}}</h3>
            {{if .UpdatedAt}}
            <time>Updated {{.UpdatedAt | fmtdate}}</time>
            {{else}}
            <time>Created {{.CreatedAt | fmtdate}}</time>
            {{end}}
        </a>
        {{end}}
    </div>
    {{end}}
</div>
{{end}}
{{define "scripts"}}
<script>
(function() {
    function setView(v) {
        var lists = [document.getElementById('doc-list'), document.getElementById('shared-list')];
        var btnCards = document.getElementById('btn-cards');
        var btnList = document.getElementById('btn-list');
        lists.forEach(function(list) {
            if (!list) return;
            if (v === 'list') {
                list.classList.add('list-view');
            } else {
                list.classList.remove('list-view');
            }
        });
        if (v === 'list') {
            btnList.classList.add('active');
            btnCards.classList.remove('active');
        } else {
            btnCards.classList.add('active');
            btnList.classList.remove('active');
        }
        localStorage.setItem('docView', v);
    }
    window.setView = setView;
    setView(localStorage.getItem('docView') || 'cards');
})();
</script>
{{end}}
```

**Step 2: Build and run**

```bash
go build ./... && go run ./cmd/server
```

Visit `http://localhost:8080` while logged in. Verify "Your Documents" section still renders. If you have an accepted collaboration, verify it appears under "Documents Shared with You".

**Step 3: Commit**

```bash
git add templates/documents.html
git commit -m "Add 'Documents Shared with You' section to dashboard"
```

---

### Task 6: Check existing routes cover the collaborator view URL

**Files:**
- Read: `cmd/server/main.go`

The collaborator view URL `/docs/{ownerDID}/{rkey}` must be registered. Confirm `CollaboratorDocumentView` and `CollaboratorDocumentEdit` are wired up. If not, add them. No code change expected here — this was built in a prior sprint — but verify before closing out.

```bash
grep -n "Collaborator" cmd/server/main.go
```

Expected: entries for `CollaboratorDocumentView` and `CollaboratorDocumentEdit`.

---

## Notes

- **No backfill needed for existing collaborators** — the `collaborations` table will be empty until invites are accepted post-deploy. This is acceptable; collaborators can re-use an existing invite link or the owner can send a new one.
- **PDS fetch errors are non-fatal** — if a shared document's owner PDS is unreachable, that card is silently skipped. Add a log line if debugging is needed.
- **`fmtdate` template func** — already registered in `cmd/server/main.go`; no changes needed.
- **List/card view toggle** — updated in Task 5 to apply to both lists so both respond to the toggle buttons.