File formats

Everything a device knows is an append-only log of entries plus the photos. The files below carry it between devices or keep it safe; none of them reaches a server.

The bundle: `.catsync`#

A zip with every entry the sender holds, one per line in JSON Lines, and the photos currently in use by their hash. Importing runs the same engine as every other transport: what is new is taken, what is known is skipped, and the bundle's version vector tells conflicts apart. Private values are inside only when the sender's switch said so. A phone and the desk read each other's bundles.

The shared folder: `catlog-sync/`#

Each device writes its own history as a run of segments, <device>.1.seg, .2.seg and so on, each a JSON Lines file of entries, and a manifest, <device>.manifest, with its version vector and the list of segments. A full segment never changes again, so a cloud client moves only the open one. Photos lie in blobs/ by hash, the signing keys in keys/. One folder carries several catalogs, each in a subfolder of its own. Every other device's files are read only.

Backups#

A full copy of a catalog, with photos, as a bundle: on the phone in the catlog-backups folder you granted, on the desk in your Downloads folder, written when the app is left after changes. Restore reads them as new catalogs.

The archive file and the go-back file#

Archiving writes the archived cats and homes with their photos to a bundle before deleting them; importing it brings them back. Going back to a moment writes everything after the moment to a bundle in the same place before removing it.

What never travels#

Camera location metadata, stripped from every stored photo. Private values without the switch. Hidden and banned things are per device and never leave it.