Files
pages/docs/design/archive-import.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

1.5 KiB

Archive Import and Knowledge City Planning

Archive import is a staged, auditable operation. Uploading an archive never writes Pages directly.

Pipeline

  1. Store the uploaded ZIP or tar-family archive in private import storage.
  2. Queue import.analyze; foreground requests always take scheduler priority.
  3. Validate entry names, link types, file count and expanded byte limits.
  4. Produce an immutable dry-run manifest containing source path, destination Path, detected content type and initial Quartier/Street/Spot suggestions.
  5. Allow a curator to edit, merge, exclude and approve suggestions.
  6. Queue import execution in bounded batches. Markdown is transpiled to the canonical HTML Document while its source representation remains available.
  7. Record created UUIDs and topology operations in an import journal so a session can be reviewed, retried or rolled back.

Safety limits

  • archive upload: 512 MiB;
  • expanded content: 2 GiB;
  • entries: 10,000;
  • absolute paths, .., NUL, hard links and symbolic links are rejected;
  • supported staging formats: ZIP, tar, tar.gz/tgz and tar.xz/txz.

Initial suggestion rules

The first directory component proposes a Quartier, the second proposes a Street, and the nearest containing directory proposes a Spot. Markdown receives higher initial confidence than opaque assets. Later scoring incorporates front matter, headings, README/index portals, internal links, vocabulary and existing City boundaries. Suggestions never mutate City topology until a curator confirms the plan.