DocsDownload
Menu

Backups, sources and the project library

On this page

Versions kept in a content-addressed store, the author’s sources, the project library, .elabora archives and machine-local data. Part of the architecture, the contract every change follows.

Backups

The user never sees git. Elabora keeps versions of the project in <data>/backups/, as a content-addressed store:

  • <data>/blobs/sha256/ab/<hash>: each file content once (shared with the journal). macOS uses copy-on-write clones, so masters cost no extra space there.
  • <data>/backups/versions/<time>-<id>.json: a version is the list of files with their hashes, plus why it was taken (auto, before-ai, after-ai, close, publish, migration, import, restore, manual), an optional name and the batch.
  • When: before and after each AI batch, every 5 minutes of activity, when the app closes, before migrations, imports and restores, and as a named version at each release build (“Published 1.2.0”). The CLI takes an automatic version before a write when the last one is older than 5 minutes, so backups exist without the app.
  • Retention: everything for 24 hours, one per hour for 7 days, one per day for 30 days, then one per week, trimmed of binary files that are neither in the current project nor in a named version. Named versions are kept until the user deletes them. Garbage collection then deletes unreferenced blobs: a deleted video leaves the backups after 30 days.
  • elabora backup list | create [--name] | restore <version> [--files <glob>] | status.

Backups do not protect against losing the disk. A copy to a second location, then the cloud, come later.

The author’s sources (D49)

The files a module is made from (a client’s brief, a deck, recorded interviews) live in sources/ at the top of the course folder, with a readable version of each that any agent can read. @elabora/node sources/ implements them; elabora sources …, the MCP tools elabora_sources, elabora_source_read and elabora_source_add, and the app call it.

  • Not the course. sources/ is outside every snapshot (project-files.ts, isSourcePath in @elabora/core project/files.ts): it is never validated, journaled, watched by the engine, backed up, restored, built or published. The validator refuses a reference into it (E_SOURCE_REFERENCED: an asset, a theme’s stylesheet, font or url(), a free object’s file), and the build checks every entry it writes and every media file it reads, and refuses a sharing image taken there. A component’s preview and a translation’s folder leave it out. The library carries it: a module’s copy (duplicateProject), its import from a folder (importFolder), its archive with sources: true; a replacement by an archive without sources keeps the module’s; the trash keeps it with the module. LibraryProject.sourcesSize gives its bytes.
  • Adding (addSources(dir, files)): files and folders copied (cloned where the file system allows it) into sources/, flat, at once. A content already there is not copied again (already-there); a name taken is numbered (« brief (2).docx »); names keep the author’s words, made portable (sources/names.ts). Hidden files are never listed (Elabora’s own work in progress among them: .adding-*, .elabora-readable-*).
  • Readable versions (sources/index.ts): sources/<name>.md and sources/<name>.files/, written on demand (makeSourcesReadable, readSource), one at a time per source in a process, from a staging folder moved into place. The first line is a marker (<!-- elabora:readable {…} -->): the source’s hash, size and time, the reader and its version, whether it is complete; listSources gives each source’s state (ready, partial, stale, missing, failed, native, unsupported), hashing a source only when its size or time changed. The readers: docx.ts (Word), pptx.ts (PowerPoint: texts, notes and the pictures each slide places, with the file’s thumbnail; image-size.ts reads a picture’s size from its header to leave out the icons, bullets and rules), recording.ts (video and audio: the transcriber of D46, frames by ffmpeg), on xml.ts (a small XML reader) and ooxml.ts (an Office package’s parts and relationships, read from the streaming ZIP reader). No program of the author’s is used: a PDF is read as it is by agents (native), and a file in an older office format (.doc, .rtf, .odt, .ppt, .pps, .odp, .key) is unsupported, its notes saying to save it as .docx or .pptx (or as a PDF). Nothing leaves the computer.

Project library and archives

The app keeps its projects in a library it manages, as Resolve does, and people exchange projects as archives. Projects stay plain folders of files: agents (Claude Code, Cowork, Codex) and the elabora command work on them by path. @elabora/node library/ implements both; elabora projects …, elabora export and elabora import call it, and the MCP server reads the library (elabora_projects_list, elabora_projects_path) but never changes it.

  • Library: a local folder that no sync service touches: ELABORA_LIBRARY when set (tests, servers), else the folder the user chose (libraryPath in <local data>/settings.json), else <local data>/Library (~/Library/Application Support/Elabora/Library on macOS, %LOCALAPPDATA%\Elabora\Library on Windows; Documents is often synced by OneDrive or iCloud). The user may move it (an external disk): on one volume the folder is renamed; across volumes everything is copied and checked by hash under every project’s lock, and the originals are removed once the setting points to the copy; .elabora-library.json marks a library, so that a move interrupted by a crash resolves to the complete copy.
  • Projects: one folder per project, named by its project id (.elabora/project-id): ids, not titles, keep paths short and valid on Windows. A new project’s id is elabora-module- and six lowercase letters and digits that cannot be misread (no 0/o, 1/l/i), drawn again while the library, its trash or ELABORA_DATA_DIR has it: the folder an AI app asks the author to trust reads as Elabora’s in any language. Projects made before keep their UUID folder; both forms are project ids, and elabora projects shows a UUID’s first eight characters or the six letters, either of which finds the project again. The index is read from the folders (course.json, file times and sizes, <data>/thumbnail.png drawn by the app), with a validation summary cached in the project’s data while its files keep their sizes and times; a project that cannot be read is listed with its error. Creating, importing and duplicating build the project in <library>/.staging/ and move it into place with one rename, so a crash never leaves half a project visible; every write to an existing project holds its lock. Renaming changes the title only, as a journaled edit of course.json. The app opens only library projects: opening a folder from elsewhere imports a copy (new id; the folder and its history stay where they are). A copy of an example the app ships records it in its data (<data>/origin.json: the example’s id and version, when the copy was made), so that the app opens that copy again rather than making another; it is machine-local, so no archive carries it.
  • Trash: deleting a project moves its folder, history included, to <library>/.trash/<time>-<id>; listTrash gives each entry its title, when it was trashed and when it will be deleted (expiresAt: 30 days after, TRASH_RETENTION_DAYS; the app deletes expired entries once per launch). An entry can be restored (restoreFromTrash: under a new id, with its history, if its id is taken again, so that it sits beside the module that holds the old one). Only deleteFromTrash (one entry, whatever its age) and emptyTrash (all, or those older than some days) delete for good; the command line has elabora projects trash delete <entry> and trash empty.
  • Archives (<course-id>.elabora, see below): the project’s files, without machine-local data; optionally with its history. Import checks the whole archive, then creates a new library project (a new id), migrates an older format and validates it; importing a course that is already in the library asks: replace it or keep both. A replacement keeps the project’s id and folder (agents working on its path keep working), takes a backup version of the project first (reason import), moves the replaced files to the trash, and keeps the project’s history. Archives are also the open-format sources delivered to clients.
  • Storyline and Rise modules are imported into the library too, as new projects (Importing Storyline and Rise modules below).
  • The elabora command still works on any folder (developers, tests, CI).
  • Later, cloud projects use the library as their local copy.

Archive format (elabora-archive/1)

A ZIP file (methods stored and deflate, no encryption, no ZIP64, so at most 4 GB), written as a stream: text files deflated, everything else stored as it is. Its entries:

  • The project’s files at the root, as listProjectFiles lists them (no .elabora/, dist/, node_modules/, OS files or sync-service conflict copies): unzipping an archive gives the course folder. With sources: true (elabora export --sources), the author’s sources and their readable versions too, under sources/, listed in files like the others (an older Elabora imports them as course files); ArchiveSummary.sources and ExportResult.sources count them apart.

  • elabora-archive.json, the manifest:

    interface ArchiveManifest {
  format: 'elabora-archive/1';
  elabora: string;                       // version of Elabora that wrote it
  exportedAt: string;                  // ISO 8601
  course: { id: string | null; title: string | null; language: string | null; format: string | null };  // from course.json
  history: boolean;
  files: { path: string; size: number; hash: `sha256:${string}` }[];         // the project files
  historyFiles: { path: string; size: number; hash: `sha256:${string}` }[];  // the entries under history/
  historyBlobsInFiles: `sha256:${string}`[];  // history contents that are project files: stored once, there
}

  • history/, with the history only: history/journal/<yyyy-mm>.jsonl (the journal as it is), history/versions/<file>.json (the backup version manifests, under their own names) and history/blobs/<sha256 hex> (the contents the versions and the journal refer to, except those listed in historyBlobsInFiles). Contents no longer in the store are left out and reported; restoring a version that needs them reports them missing.

Import refuses, before writing anything: a ZIP without manifest (a zipped folder: unzip it and import the folder), a manifest of an unknown or newer format, an entry name that is absolute, has .. or . segments, backslashes or a drive letter, a project file in a tool folder (.elabora/ and the others), a history/ entry of another kind than these three, names that differ only by case or put a file where a folder is, an entry the manifest does not list or a listed one that is missing or has another size. It then extracts into the library’s staging folder, checks each file’s SHA-256 (and each ZIP CRC), refuses a journal with an operation outside the project’s files and a version manifest the backups cannot read, and only then moves the project into place. The hashes catch damage and hand edits; they are not a signature. Readers ignore manifest fields they do not know; a new format version (elabora-archive/2) comes with a reader of the older ones, which brings them to the current form before anything else (migrateManifest in library/archive.ts).

Machine-local data

A project’s journal, lock, blob store, backups, media jobs, renditions, caches and previews are machine-local data. @elabora/node projectDataDir(projectDir) (data-dir.ts) says where they live, and every module goes through it; nothing joins .elabora/ by hand. By default it is the project’s own .elabora/ folder; ELABORA_DATA_DIR moves every project’s data under a folder (tests, servers), keyed by the id kept in .elabora/project-id. The agents’ activity (activity.jsonl, kept a day) and the transcripts of Elabora’s chat (chats/<chat>.jsonl, written by the app, read by @elabora/node/chats) are there too, as is what this computer published of a course to Elabora’s hosting (cloud/publications.json, D43); the hosting’s credentials are not project data: they are in the user’s local data (credentials/), with the ElevenLabs key.

Blobs and backups copy files as clones where the file system shares blocks (APFS through cp -c, because Node 24 does not clone on macOS; Btrfs and XFS through COPYFILE_FICLONE_FORCE); NTFS has no clones, so on Windows a master costs its size again in the store.

A folder used with the CLI may still sit in a synced folder: conflict copies left by sync services are reported (W_SYNC_CONFLICT_COPY) instead of being loaded as content, and writes retry on Windows sharing violations (EBUSY, EPERM).