Single-Writer SQLite/Yjs Architecture

flowchart TD
  subgraph CLI["CLI Process (apps/fp)"]
    CLIW["writes.ts\ncreateIssue / updateIssue / deleteIssue"]
    CLISYNC["syncIssues\none-shot sync"]
  end

  subgraph Desktop["Desktop App (apps/desktop)"]
    subgraph Main["Main Process"]
      IPC["IPC Handler\nissue-handler.ts"]
      OPT["optimisticMutation\nseq-guarded broadcast"]
      WATCHER["DatabasePoller\nPRAGMA data_version\n300ms poll"]
      PUSH["enqueuePushUpdates\nbuffered push queue"]
    end

    subgraph Sync["Sync Utility Process"]
      SLOOP["Sync Loop\n5min dormant cycle"]
      SOPS["syncIssues\nCRDT merge"]
    end

    subgraph Renderer["Renderer Process"]
      ZUST["Zustand Store\nissues map + details"]
      HOOK["useIssueSync\nevent listener"]
    end
  end

  subgraph Storage["SQLite — fp.db"]
    YJS["yjs_updates\nbinary CRDT deltas"]
    SNAP["yjs_snapshots\ncompacted state"]
    IDX["issues_index\ndenormalized cache"]
  end

  SERVER["Fiberplane Server\nFpProjectSyncDO"]

  CLIW -->|"saveUpdateStrict + upsertIndex"| YJS
  CLIW -->|"best-effort"| IDX
  CLISYNC <-->|"WebSocket handshake"| SERVER

  IPC -->|"edit intent"| OPT
  OPT -->|"ISSUES_PATCH (optimistic)"| HOOK
  OPT -->|"persist via fp-core"| YJS
  OPT -->|"issue IDs"| PUSH
  PUSH -->|"PUSH_UPDATES msg"| SLOOP

  SLOOP --> SOPS
  SOPS <-->|"WebSocket sync"| SERVER
  SOPS -->|"saveLocalUpdate"| YJS
  SOPS -->|"SYNC_UPDATE / NEW_ISSUE"| IPC

  WATCHER -->|"poll data_version"| YJS
  WATCHER -->|"ISSUES_PATCH (cross-proc)"| HOOK

  HOOK --> ZUST

  classDef cli fill:#b5761422,stroke:#b57614,stroke-width:2px
  classDef main fill:#1e3a5f22,stroke:#1e3a5f,stroke-width:2px
  classDef sync fill:#6e3a6e22,stroke:#6e3a6e,stroke-width:2px
  classDef renderer fill:#0e7c6b22,stroke:#0e7c6b,stroke-width:2px
  classDef storage fill:#4a7c3f22,stroke:#4a7c3f,stroke-width:2px
  classDef server fill:#9e3a1a22,stroke:#9e3a1a,stroke-width:2px

  class CLIW,CLISYNC cli
  class IPC,OPT,WATCHER,PUSH main
  class SLOOP,SOPS sync
  class ZUST,HOOK renderer
  class YJS,SNAP,IDX storage
  class SERVER server
    

sequenceDiagram
  participant CLI as CLI Process
  participant DB as fp.db (SQLite)
  participant POLL as DatabasePoller
  participant MAIN as Main Process
  participant REND as Renderer

  CLI->>DB: saveUpdateStrict INSERT yjs_updates
  Note over DB: data_version increments

  loop Every 300ms
    POLL->>DB: PRAGMA data_version
    POLL->>POLL: Compare with last known version
  end

  POLL->>DB: Detected change! Wait 50ms settle
  POLL->>DB: SELECT id, issue_id FROM yjs_updates WHERE id > lastSeenId
  POLL->>POLL: Filter out own-process writes via recentOwnWrites map

  POLL->>MAIN: Emit issues-patched event with changedIds
  MAIN->>MAIN: Read full issues from SQLite
  MAIN->>MAIN: Build IssueSummary array, bump patchSeq
  MAIN->>REND: Broadcast ISSUES_PATCH with seq + updates
  REND->>REND: useIssueSync merges into Zustand store
  REND->>REND: React re-renders with new data
    

flowchart TD
  subgraph Push["Push: Local to Server"]
    A1["Local write completes"] --> A2["enqueuePushUpdates\nbuffer issue IDs"]
    A2 --> A3["PUSH_UPDATES message\nto sync worker"]
    A3 --> A4["syncIssues one-shot\nWebSocket handshake"]
    A4 --> A5["Server merges CRDT"]
  end

  subgraph Pull["Pull: Server to Local"]
    B1["Sync loop triggers\n5min dormant cycle"] --> B2["syncIssues one-shot\nload local SVs"]
    B2 --> B3["Server sends new updates"]
    B3 --> B4["saveLocalUpdate\nINSERT yjs_updates + reindex"]
    B4 --> B5["SYNC_UPDATE message\nto main process"]
    B5 --> B6["handleSyncIssueUpdate\nskipNextUpdate + broadcast"]
    B6 --> B7["ISSUES_PATCH\nto all renderers"]
  end

  classDef push fill:#4a7c3f22,stroke:#4a7c3f,stroke-width:2px
  classDef pull fill:#6e3a6e22,stroke:#6e3a6e,stroke-width:2px

  class A1,A2,A3,A4,A5 push
  class B1,B2,B3,B4,B5,B6,B7 pull