sealight.xyz / seams.so
Social Annotations in the Atmosphere
15
fork

Configure Feed

Select the types of activity you want to include in your feed.

seams.so / history / SIMPLIFICATION_PLAN.md
at main 3.2 kB view raw view code
Anish Lakhwara WIP 2: electric bugaloo
78fa8b51

Comprehensive Simplification & Reliability Plan#

Based on the Oracle's review, this plan focuses on simplifying the architecture by enforcing "Storage as Source of Truth," standardizing messaging, and aligning with AT Protocol patterns.

Phase 1: Core Protocol & Runtime Definition#

Goal: Establish a shared vocabulary for all components to prevent drift and ad-hoc logic.

  • Create packages/core/src/constants.ts
    • Move Protocol Constants: ANNOTATION_COLLECTION, COMMENT_COLLECTION.
    • Define Storage Keys: STORAGE_KEY_PREFIX (e.g., seams:), ANNOTATIONS_KEY_PREFIX.
    • Define XRPC Endpoints: XRPC_CREATE_RECORD, XRPC_GET_RECORD.
  • Create packages/core/src/messages.ts
    • Define a strict Union Type for all internal messages:
      • SYNC_CACHE: Trigger a sync from backend to storage.
      • GET_STATE: Request current selection/auth state.
      • SELECTION_CHANGED: Notify that user selected text.
      • PAGE_URL_CHANGED: Notify that the URL changed (SPA nav).
      • LOGIN / LOGOUT: Auth state changes.
  • Refactor packages/core/src/types.ts
    • Ensure Annotation type clearly distinguishes between "UI Shape" and "ATProto Record Shape" (if they differ).
    • Add strict types for Selectors.

Phase 2: Unifying the Message Bus#

Goal: Remove ad-hoc sendMessage calls and use a type-safe wrapper.

  • Create Messenger class in Core
    • A simple wrapper around browser.runtime.sendMessage (Extension) and postMessage (Proxy).
    • Methods: send(msg: Message), on(type, handler).
  • Refactor Extension to use Messenger
    • Update background/extension.ts and content/extension.ts.
    • Remove any raw string message matching.
  • Refactor Proxy to use Messenger
    • Update via-client/main.ts and via-client/sidebar.ts to match the same protocol.

Phase 3: Storage-First Enforcement#

Goal: Decouple UI from Network. The UI should only render what is in Storage.

  • Audit & Refactor ContentScript
    • Verify it only renders in response to storage.onChanged.
    • Remove any direct "fetch and render" logic triggered by page load (replace with "load from storage, then trigger background sync").
  • Audit & Refactor Sidebar
    • Ensure it reads annotations from storage, not from a message response.
  • Standardize Sync Logic
    • Extension: Ensure BackgroundWorker is the only writer to annotations:* storage keys.
    • Proxy: Create a simple "Worker" in the client script (or sidebar) that polls the backend and writes to localStorage.

Phase 4: AT Protocol & Backend Alignment#

Goal: Treat the PDS/Backend interaction as a stable API surface.

  • Refactor packages/core/src/pds/index.ts
    • Use constants from constants.ts.
    • Ensure createAnnotation uses the strict Record type.
  • Align Backend (server/)
    • Update Go structs to match the Core Annotation types/constants (manually for now, but strict).
    • Ensure the "Index" endpoint expects exactly what the frontend sends.

Phase 5: Documentation#

  • Update README.md or create ARCHITECTURE.md
    • Document the "Storage Flow" (Diagrams from Oracle).
    • Document the "Message Vocabulary".