Skip to main content

Desktop Notes

These notes describe the current Notary experience in Bookcicle Desktop.

Main Layers​

The current desktop notary stack is split across three layers:

LayerRole
UIDashboard, verification, onboarding, settings, exports
CoreProofs, checkpoints, watchers, verification, bundle export
Agent / APIBackground automation and remote notary calls

Main Modules​

UI layer​

This layer wires the desktop shell to:

  • the Notary dashboard
  • the verification view
  • the inbox and related service areas

Core layer​

This layer owns the durable notary behavior.

Agent and remote access​

This layer handles:

  • long-running watcher and reconcile loops
  • auto-attest cycles
  • anchor status polling
  • remote attest and verify calls

In other words, desktop owns a big part of the Local Proofs side of the model, then uses remote workflows to add Attest receipts and Anchors later.

Settings Surfaces​

The desktop app exposes four main Notary settings panels.

Watchers​

Current options include:

  • enable or disable watchers
  • allow file watchers
  • allow folder watchers
  • cadence presets for file watchers
  • cadence presets for folder watchers
  • folder exclude list display
  • OS notifications
  • total watcher cap
  • per-project watcher cap
  • duplicate watcher rejection

Checkpoints​

Current options include:

  • enable or disable checkpoints
  • max checkpoint size
  • max total checkpoint storage
  • retention by age
  • retention by count per project
  • dedupe by Merkle root
  • garbage collect on write
  • copy checkpoint directory
  • copy checkpoint JSON

Auto-Attest​

Current options include:

  • enable or disable auto-attest
  • include watcher proofs
  • include manual proofs
  • run interval in minutes
  • per-project minimum gap in hours
  • monthly cap
  • auto-checkpoint cadence
  • future overage toggle in dev-visible flows

These settings control how often eligible local proofs are upgraded into Bookcicle server receipts.

Persistent Agent​

The desktop UI exposes runtime status for:

  • installed
  • enabled
  • running
  • version
  • last error

The panel also lets the user:

  • toggle persistent background behavior
  • repair drift
  • probe runtime status

Verification and Export​

This area is responsible for:

  • opening proof artifacts
  • collecting evidence
  • running offline and online checks
  • classifying results
  • exporting reports and portable bundles

Receipt verification details​

The current verification code checks Attest receipts at multiple levels:

  • Offline receipt binding: compare the receipt merkle root with the local proof merkle root
  • Online public receipt verification: verify the server receipt signature without requiring auth
  • Online receipt match: when auth or share access is available, fetch the authoritative cloud receipt and compare it with the embedded receipt in the capsule

That is the main reason Desktop is the best place to inspect Attest receipts deeply today.

Background Agent Contract​

The agent is responsible for:

  • running watchers continuously
  • keeping the index reconciled
  • scheduling anchor status checks
  • supporting OS-managed startup
  • running auto-attest cycles that add server receipts to eligible local proofs

Important behavior note:

  • when persistent agent is off, the app still starts a session agent while Bookcicle is open
  • when persistent agent is on, automation continues after app close