appa
Peer-to-peer file synchronization in Rust on iroh.
rust p2p iroh sync
Star 100
Fork 2
Watch
appa docs architecture.md
2.7 kB · 65 lines
Markdown
at main

Appa architecture #

Appa is local-first folder synchronization. One daemon owns the local Iroh endpoint, SQLite state, file watchers, and synchronization loop. Clients use a user-owned local socket.

Model #

  • A folder is a local directory with a stable ID, local mode, manifest, capability, and signed roster.
  • A device is an Appa installation identified by its Iroh public key.
  • A member is a device named in a folder roster. Members may own, write, or read a folder.
  • A capability is the folder secret carried by invitations and control requests. It is not stored in folder-inventory files.
  • A peer is a direct or relay route to a member device.

The daemon discovers LAN routes with mDNS and uses Iroh relays when needed.

Synchronization #

  1. A scan builds a manifest and imports changed file data into the blob store.
  2. Peers compare manifest Merkle trees and exchange only changed entries.
  3. Version clocks decide whether a change is newer or concurrent.
  4. Concurrent edits become conflict copies rather than silently overwriting a file.
  5. Missing blobs are fetched before filesystem materialization. A pending materialization record permits recovery after interruption.

Announcements improve latency. Periodic peer checks still converge when an announcement is missed.

Audit evidence #

Local revision history is compact and bounded for restore. The audit log is append-only and retained independently.

Every device has a signed chain of audit events. Each event includes its parent hash, manifest root, and roster hash. Peers exchange missing events through the authenticated control protocol. A device that retained a newer head can detect a later rollback, altered event, omission, or conflicting event at the same author sequence.

Audit verification detects changes relative to heads retained by other members. A compromised device key can still sign events.

Local state #

Appa state includes the device identity, SQLite database, blob cache, and daemon socket. APPA_HOME changes its location. It is separate from synced folders.

appa folder remove <folder> removes local Appa state without touching files or remote membership. Folder inventories are optional local input files for bulk registration and mode changes. Invitations remain the only way to join an existing shared folder.

Format boundaries #

  • appa/sync/4 is the authenticated Iroh control protocol.
  • Invitation format version 5 covers signed invitation payloads.
  • Folder format version 2 covers rosters and manifests.
  • Folder inventory format version 1 covers appa.toml.

SQLite state uses a migration ladder.