Social Annotations in the Atmosphere
docs: move refactor plan to history/ and add architectural context
Amp-Thread-ID: https://ampcode.com/threads/T-b47d9290-07a2-4f73-b491-a0a1026c85e5
Co-authored-by: Amp <amp@ampcode.com>
+21
-8
+21
-8
REFACTOR_PLAN.md
history/REFACTOR_PLAN.md
+21
-8
REFACTOR_PLAN.md
history/REFACTOR_PLAN.md
···
1
1
# Seams Refactoring Plan
2
2
3
+
## Understanding the Project
4
+
5
+
Before starting any work, please review the documentation in the `history/` directory and `AGENTS.md`.
6
+
7
+
- **`AGENTS.md`**: The primary source of truth for system architecture, data flow, and development commands.
8
+
- **`history/STORAGE_FIRST_ARCHITECTURE.md`**: Details the "Storage-First" architecture used by the extension to ensure performance and offline capability.
9
+
10
+
### Architecture Highlights
11
+
- **Extension**: Uses WXT, `browser.storage.local` for state, and a background worker for syncing.
12
+
- **Backend**: Go server with SQLite, indexing annotations from PDS via AT Protocol.
13
+
- **Proxy**: A "via" style proxy for annotating pages without the extension installed.
14
+
- **Landing**: A static landing page that displays a feed of global annotations.
15
+
3
16
## Phase 1: Core Data & Backend Standardization (Completed)
4
17
- [x] **Standardize Annotation Type** (`server/internal/models/annotation.go`)
5
18
- Aligned Go `Annotation` struct with TypeScript definition and ATProto schema.
···
27
40
- [x] **Integrate into Landing** (`landing/landing.js`)
28
41
- Import and use the web component, removing duplicate rendering code.
29
42
30
-
## Phase 3: OAuth Flow Modernization
31
-
**Goal:** Improve authentication experience by removing popups.
32
-
- [ ] **Switch to Same-Tab OAuth** (`packages/core/src/oauth/launchers.ts`)
33
-
- Modify `WebOAuthLauncher` to use `window.location.assign`.
34
-
- [ ] **Handle OAuth Redirects** (`entrypoints/via-client/oauth-callback.ts`)
35
-
- Update callback to redirect back to origin using stored state.
36
-
37
-
## Phase 4: Content Script & Proxy Refactoring
43
+
## Phase 3: Content Script & Proxy Refactoring
38
44
**Goal:** Clean up proxy client architecture and share logic.
39
45
- [ ] **Rename Proxy Script** (`packages/core/src/content/script.ts`)
40
46
- Rename `ContentScript` to `ProxyContentScript`.
···
44
50
- Implement `notifySelectionChange` in proxy script.
45
51
- [ ] **Cleanup Event Handling**
46
52
- Fix logic for detecting clicks inside/outside UI.
53
+
54
+
## Phase 4: OAuth Flow Modernization
55
+
**Goal:** Improve authentication experience by removing popups.
56
+
- [ ] **Switch to Same-Tab OAuth** (`packages/core/src/oauth/launchers.ts`)
57
+
- Modify `WebOAuthLauncher` to use `window.location.assign`.
58
+
- [ ] **Handle OAuth Redirects** (`entrypoints/via-client/oauth-callback.ts`)
59
+
- Update callback to redirect back to origin using stored state.
47
60
48
61
## Phase 5: Optimization & Cleanup
49
62
**Goal:** Performance improvements and dead code removal.