# 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.