TidGi-Desktop/docs/internal/IPCSyncAdaptorAndFSAdaptor.md

Sync Architecture: IPC and Watch-FS Plugins

This document describes how the tidgi-ipc-syncadaptor (frontend) and watch-filesystem-adaptor (backend) plugins work together to provide real-time bidirectional synchronization between the TiddlyWiki in-memory store and the file system.

Architecture Overview

Frontend (Browser)                    Backend (Node.js Worker)
┌─────────────────────────────┐      ┌─────────────────────────────────────┐
│ TiddlyWiki                  │      │ TiddlyWiki (Server)                 │
│ In-Memory Store             │      │ In-Memory Store                     │
└──────────┬──────────────────┘      └──────────┬──────────────────────────┘
           │                                    │
           │ TidGiIPCSyncAdaptor                │ WatchFileSystemAdaptor
           │ (syncadaptor)                      │ (syncadaptor)
           │                                    │
           │                                    ├── FileSystemWatcher
           │                                    │   (monitors files via nsfw)
           │                                    │
           ├─── Save via IPC ──────────────────►│
           │                                    │
           │◄────── IPC Observable ─────────────┤
           │        (Change Events)             │
           │                                    │
           │                                    ├── FileSystemAdaptor
           │                                    │   (read/write files)
           │                                    │
           │                                    ▼
           │                                 File System
           └────────────────────────────────────┘

Key Design Principles

1. Single Source of Truth: File System

• Backend watch-fs monitors the file system using nsfw library
• All file changes (external edits, saves from frontend) flow through file system
• Backend wiki state reflects file system state

2. Syncer-Driven Updates (Refactored Architecture)

Previous Approach (Problematic):

• FileSystemWatcher directly called wiki.addTiddler() when files changed
• Led to echo problems and complex edge case handling

Current Approach (Syncer-Driven):

• FileSystemWatcher only collects changes into updatedTiddlers list
• Triggers $tw.syncer.syncFromServer() to let TiddlyWiki's syncer handle updates
• Syncer calls getUpdatedTiddlers() to get change list
• Syncer calls loadTiddler() for each modified tiddler
• Syncer uses storeTiddler() which properly updates changeCount to prevent echo

Benefits:

• Leverages TiddlyWiki's built-in sync queue and throttling
• Proper handling of batch changes (git checkout)
• Eliminates echo loops via syncer's changeCount tracking

3. Two-Layer Echo Prevention

IPC Layer (First Defense):

• ipcServerRoutes.ts tracks recently saved tiddlers in recentlySavedTiddlers Set
• When wiki.addTiddler() triggers change event, filter out tiddlers in the Set
• Prevents frontend from receiving its own save operations as change notifications

Watch-FS Layer (Second Defense):

• When saving/deleting, watch-fs temporarily excludes file from monitoring
• Prevents watcher from detecting the file write operation
• Re-includes file after operation completes (with delay for nsfw debounce)

4. IPC Observable for Change Notification

• Backend sends change events to frontend via IPC Observable pattern (via ipc-cat)
• Frontend subscribes to getWikiChangeObserver$ observable from window.observables.wiki
• Change events trigger frontend's syncFromServer() to pull updates

Module Responsibilities

FileSystemWatcher (Backend - New)

Purpose: Monitor file system changes without directly modifying wiki state

Key Features:

• Uses nsfw library for native file system watching
• Maintains updatedTiddlers list for pending changes
• Implements getUpdatedTiddlers() for syncer integration
• Implements loadTiddler() for lazy loading from file system
• Handles git revert/checkout via delayed deletion processing
• Manages file exclusion list for echo prevention

Key Methods:

• getUpdatedTiddlers(syncer, callback): Returns collected changes
• loadTiddler(title, callback): Loads tiddler content from file
• excludeFile(path): Temporarily exclude file from watching
• scheduleFileInclusion(path): Re-include file after delay

WatchFileSystemAdaptor (Backend)

Purpose: Coordinate between FileSystemWatcher and syncer, implement syncadaptor interface

Key Features:

• Extends FileSystemAdaptor for file save/delete operations
• Delegates file watching to FileSystemWatcher
• Implements full syncadaptor interface for Node.js syncer
• Coordinates file exclusion during save/delete operations

Key Methods:

• getUpdatedTiddlers(): Delegates to FileSystemWatcher
• loadTiddler(): Delegates to FileSystemWatcher
• saveTiddler(): Saves to file with exclusion handling
• deleteTiddler(): Deletes file with exclusion handling

FileSystemAdaptor (Backend - Base Class)

Purpose: Handle tiddler file save/delete operations with sub-wiki routing

Key Features:

• Routes tiddlers to sub-wikis based on tags
• Generates file paths using TiddlyWiki's FileSystemPaths
• Handles external attachment file movement
• Provides retry logic for file lock errors

TidGiIPCSyncAdaptor (Frontend)

Purpose: Bridge between frontend TiddlyWiki and backend file system

Key Features:

• Communicates via IPC using tidgi:// custom protocol
• Subscribes to change events via IPC Observable
• Maintains updatedTiddlers list from IPC events
• Implements full syncadaptor interface for browser syncer

Data Flow Examples

Example 1: User Edits in Frontend

1. User clicks save in browser
   ├─► Frontend syncer calls saveTiddler()
   │
2. TidGiIPCSyncAdaptor.saveTiddler()
   ├─► IPC call to putTiddler in ipcServerRoutes.ts
   │
3. ipcServerRoutes.putTiddler()
   ├─► Marks tiddler in recentlySavedTiddlers (IPC echo prevention)
   ├─► Calls wiki.addTiddler() (triggers change event)
   ├─► Change event filtered by recentlySavedTiddlers
   │
4. Backend syncer detects change
   ├─► Calls WatchFileSystemAdaptor.saveTiddler()
   │
5. WatchFileSystemAdaptor.saveTiddler()
   ├─► Excludes file path from watching
   ├─► Calls FileSystemAdaptor.saveTiddler()
   ├─► Writes file to disk
   ├─► Schedules file re-inclusion after delay
   │
6. nsfw might detect file change
   ├─► FileSystemWatcher checks exclusion list
   ├─► File is excluded, event ignored

Example 2: External Editor Modifies File

1. User edits file in VSCode/Vim
   ├─► File content changes on disk
   │
2. nsfw detects file change
   ├─► File NOT in excludedFiles
   │
3. FileSystemWatcher.handleFileAddOrChange()
   ├─► Adds title to updatedTiddlers.modifications
   ├─► Stores file info in pendingFileLoads
   ├─► Schedules syncer trigger (debounced 200ms)
   │
4. $tw.syncer.syncFromServer() called
   ├─► Creates SyncFromServerTask
   │
5. SyncFromServerTask.run()
   ├─► Calls getUpdatedTiddlers()
   ├─► Gets modifications/deletions list
   ├─► Adds titles to titlesToBeLoaded
   │
6. For each title to load:
   ├─► LoadTiddlerTask.run()
   ├─► Calls loadTiddler(title)
   ├─► FileSystemWatcher loads from file
   ├─► syncer.storeTiddler() updates wiki
   ├─► Properly sets changeCount (prevents echo save)
   │
7. wiki.addTiddler() triggers change event
   ├─► getWikiChangeObserver sends to frontend
   │
8. Frontend receives change
   ├─► TidGiIPCSyncAdaptor adds to updatedTiddlers
   ├─► Frontend syncer.syncFromServer()
   ├─► Frontend loadTiddler() via IPC
   ├─► Frontend wiki updated

Example 3: Git Checkout (Batch Changes)

1. User runs git checkout
   ├─► Many files deleted/created/modified
   │
2. nsfw debounces events (100ms)
   ├─► Multiple events batched together
   │
3. FileSystemWatcher.handleNsfwEvents()
   ├─► For each DELETED file:
   │   └─► Schedule deletion with 100ms delay
   │       (handles git revert/checkout pattern)
   ├─► For each CREATED/MODIFIED file:
   │   └─► Cancel any pending deletion for same path
   │   └─► Add to updatedTiddlers.modifications
   │
4. Syncer trigger debounced (200ms)
   ├─► All changes collected before sync starts
   │
5. Single SyncFromServerTask processes all changes
   ├─► All modifications queued for loading
   ├─► All deletions processed (wiki.deleteTiddler)
   │
6. LoadTiddlerTasks process sequentially
   ├─► Each tiddler loaded from file
   ├─► Frontend notified via IPC Observable

Key Configuration

Timing Constants

// FileSystemWatcher.ts
FILE_DELETION_DELAY_MS = 100; // Delay before processing DELETE events
FILE_INCLUSION_DELAY_MS = 150; // Delay before re-including file after save
GIT_NOTIFICATION_DELAY_MS = 1000; // Debounce for git status notification
SYNCER_TRIGGER_DELAY_MS = 200; // Debounce for syncer trigger

Syncer Configuration

• Frontend: pollTimerInterval = 2_147_483_647 (effectively disabled)
• All updates come via IPC Observable (event-driven)

Troubleshooting

Changes Not Appearing in Frontend

1. Check IPC Observable connection: Look for [test-id-SSE_READY] in logs
2. Verify watch-fs is running: Look for [test-id-WATCH_FS_STABILIZED]
3. Check file exclusion: Should see file being excluded then included

Echo/Duplicate Updates

1. Check recentlySavedTiddlers filtering in ipcServerRoutes.ts
2. Verify file exclusion during save/delete operations
3. Check syncer's changeCount tracking

Git Checkout Issues

1. Ensure FILE_DELETION_DELAY_MS is working (files not prematurely deleted)
2. Check that SYNCER_TRIGGER_DELAY_MS allows batch collection
3. Verify syncer processes all changes in single SyncFromServerTask

Sub-Wiki Not Syncing

1. Check sub-wiki watcher initialization: Look for [WATCH_FS_SUBWIKI] logs
2. Verify tiddlywiki.info has correct configuration
3. Check workspace subWikiFolders setting

Design Decisions

Why Syncer-Driven Instead of Direct Updates?

1. Echo Prevention: Syncer's storeTiddler() properly updates changeCount, preventing save loops
2. Batch Handling: Syncer queues all changes and processes them sequentially
3. Throttling: Built-in throttle prevents rapid-fire saves
4. Error Recovery: Syncer has built-in retry logic

Why Two-Layer Echo Prevention?

1. IPC Layer: Prevents frontend from seeing its own saves via IPC
2. Watch-FS Layer: Prevents file watcher from seeing our own file writes
3. Both needed: IPC prevents wiki→wiki echo, Watch-FS prevents file→wiki echo

Why Delay DELETE Events?

Git operations often delete then recreate files quickly. The delay allows:

1. CREATE event to arrive and cancel pending DELETE
2. Treat as modification instead of delete+create
3. Prevents "missing tiddler" errors during git operations