dorfteich/docs/architecture/pond-archive-format.md

Pond archive format (issue #305)

Format version 1.

The archive a pond admin downloads before deleting a pond, and the one a Site Admin downloads before purging one. It is a preservation format, not a backup: Dorfteich has no importer for it, deliberately. What this document buys is that one can be written later without guesswork.

Do not confuse it with two neighbours:

	contains	purpose
Markdown export (GET /ponds/:id/export/markdown, #65)	readable pages + the images they embed	everyday "give me my text"
Pond archive (this document)	readable pages + all attachments + settings, labels, comments, hierarchy	last resort before deletion
Restore set (ADR 0015)	the whole instance, database and data directories	operational recovery

Layout

README.txt        plain-text version of this warning, for whoever unpacks it
manifest.json     everything Markdown cannot carry (see below)
pages/<slug>.md   one file per page, Markdown, wikilinks rewritten to
                  relative links, media references rewritten to media/…
media/<id>.<ext>  EVERY attachment of the pond — including ones no page
                  embeds, which is the whole point of this archive
media/<id>.<ext>.classification.txt
                  companion marking for a classified attachment (#212): the
                  binary cannot carry it, and this file survives copying

manifest.json

{
  "kind": "dorfteich-pond-archive",
  "formatVersion": 1,
  "exportedAt": "2026-08-01T18:00:00.000Z",

  // False when the exporter could not read every page. Stated in the archive
  // itself so a later reader is never misled about what they hold.
  "complete": true,
  "omittedPages": 0,

  // Highest classification contained (ADR 0022), stated once.
  "classification": "unclassified",

  "pond": { "name": "…", "slug": "…", "type": "SHARED", "createdAt": "…", "settings": { … } },
  "labels": [{ "id": "…", "name": "…", "color": "…", "parentId": null }],
  "pages": [
    {
      "id": "…", "slug": "…", "title": "…",
      "parentId": null,          // the hierarchy Markdown cannot express
      "sortKey": "…",            // sibling order (ADR 0012's fractional key)
      "classification": "unclassified",
      "labelIds": ["…"],
      "createdAt": "…", "updatedAt": "…",
      "file": "pages/<slug>.md"
    }
  ],
  "comments": [
    {
      "id": "…", "pageId": "…", "parentId": null, "body": "…",
      "author": "Display Name",  // NOT the account id — see below
      "createdAt": "…", "editedAt": null, "resolvedAt": null
    }
  ],
  "attachments": [
    {
      "id": "…", "pageId": "…" | null, "fileName": "…", "mimeType": "…",
      "sizeBytes": 1234,
      "sha256": "…",             // #199, so a reader can verify the bytes
      "createdAt": "…", "file": "media/<id>.<ext>"
    }
  ],
  "files": [{ "path": "…", "classification": "unclassified" }]
}

Decisions a reader should know about

• formatVersion is a contract. A reader that does not recognise the version should refuse rather than guess. Additive fields do not bump it; a change in meaning does.
• Comments name a display name, not an account. The archive is a document that outlives the instance; an account id would be an unresolvable reference the moment the account is gone.
• files is the #210 property, kept. Every file with its level, so the bulk-egress channel stays machine-checkable after the ZIP is unpacked and copied onward.
• An attachment with no page inherits the pond's highest classification. Nothing narrower governs it, and fail-closed is the rule (ADR 0022).
• Incomplete archives are labelled, not refused. A pond admin who cannot read every page still gets what they may read — with complete: false and the count of what is missing, in the manifest and in the UI before the download.

Read trail

The archive is a bulk-egress channel. One export read event is written per classified page before any classified byte enters the stream (ADR 0023), so a failed write aborts the download with the evidence intact. Attachments never travel without their page, so they are covered by the same events.

The download itself is audited as pond.archived (catalogue v1.7) with the page and attachment counts, the number of omitted pages, and whether the archive was complete.

What is NOT in it

• Page history and Yjs update logs. The Markdown is the current state.
• Permissions and memberships: they name accounts of this instance, which an archive read elsewhere cannot resolve.
• Anything from the trash: trashed pages are not exported.

An importer will therefore recreate a pond's content, structure and discussion — not its history or its access rules. That is a deliberate scope, not an oversight.