A file-naming convention plus a few single-file HTML tools for managing project deliverables. Start with Browse — open any folder, no setup. Self-contained, offline-capable, dependency-free.
+Three small tools for managing project deliverables, plus a simple file-naming convention. Each tool is one HTML file that runs entirely in your browser — open it, point it at a folder on your computer, and go. Nothing to install, no account, no server. Your files never leave your machine.
+ZDDC is a convention, not a platform. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain shared folder becomes a fully searchable, auditable information-management system — no server, no database, no software required to read the archive.
-The tools below are optional interfaces around this structure, and each needs nothing to run. Every one is a single self-contained HTML file: open it and point it at a folder on your disk, or put it behind any web server (including the optional zddc-server described below) and use it over the network. Same on-disk layout either way. The extra niceties — friendly labels, per-folder tools, permissions — come from optional .zddc files you can add later, or never.
ZDDC is a convention, not a platform. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain folder on your computer or a shared drive becomes a fully searchable, auditable record — no server, no database, no software required to read it.
+The three tools below are optional helpers around this structure. Each is a single HTML file that works entirely on your own machine: open it, pick a folder, and you're working. They run offline and never upload anything. You can start with Browse on your existing files right now — there's nothing to set up first.
Each tool is a single self-contained HTML file. The link below always tracks the current stable; pin to a specific version on the releases page for reproducibility.
+Three single-file apps. Click one to open it now, or right-click → Save As to keep your own copy — each works offline forever, with no install and no updates.
-.zddc files and the same tool gains friendly folder labels, per-folder tools, permissions, and transmittal actions — leave them out and it's still a complete browser.Append ?v=v0.0.4 to any URL to load a specific version for a single request — useful for sharing a link to an exact build. Direct local-folder access requires a Chromium-based browser (the File System Access API is unavailable in Firefox / Safari). Browse all versions →
The tools work two ways over the same on-disk archive. Pick whichever fits your team:
- -Open a tool, click Add Directory, point it at a folder. The tool reads files via the File System Access API. No upload, no server, no account.
-Enough for individual users and small teams on a shared drive (network share, Dropbox, OneDrive, syncthing).
-Take the same local directory and put it behind any web server (nginx, Caddy, Apache, or zddc-server). The Archive tool talks to the server's directory listings instead of the local filesystem — read-only, works in any browser.
zddc-server is an optional web-server app, purpose-built to serve a ZDDC archive over the network. Any web server gives you read-only online mode; zddc-server adds the things a generic one can't:
.zddc files along the tree to say who can read, write, create, or delete each folder — by email, wildcard, or named role. Write-once (WORM) archive folders keep the issued record immutable. How the cascade works →.archive URL always resolves to the current revision of any document.The on-disk layout is the same in both modes. Stop the server and the directory is still a perfectly valid ZDDC archive that opens in local-directory mode. The server is convenience, not lock-in.
- -Source, configuration, and the full ACL reference: codeberg.org/VARASYS/ZDDC zddc/.
Two paths, no install scripts. The server has built-in fetch-and-cache for the tool HTMLs; the local-file path needs nothing more than a download.
- -The app has the current-stable build of the tools baked in. They appear automatically at the right paths in the served tree:
-archive/ path — the read-only search-and-export view of the formal recordWhich tool serves at a given URL is decided by the .zddc cascade — the embedded defaults map archive/ subtrees to the archive tool and everything else to browse, but operators can override per folder via default_tool:. Folder names are case-insensitive — Working/, working/, and WORKING/ all match the same rule.
./zddc-serverNo flags needed for a quick start. The served tree defaults to the current working directory; the listener defaults to https://localhost:8443/ with a self-signed certificate. --root, --addr, and --tls-cert / --tls-key override each. --help prints the full flag list.
To override a tool at any path: drop a real .html file there — that file wins over the baked-in version. To pin a different version, write an apps: entry in any .zddc file along the path:
# <project>/.zddc
-apps:
- browse: stable # latest stable, or v0.0.4 to pin an exact version
- archive: https://my-fork.example/archive.htmlURL sources are fetched once and cached in <ZDDC_ROOT>/_app/. To force a re-fetch, delete the cache file. Closer-to-leaf .zddc entries override parent ones.
No server, no install — open in any modern browser.
-Right-click → Save As. Each tool is a self-contained HTML file with everything inlined; works from file:// or any static host.
To open a folder straight from your computer, use a Chromium-based browser — Chrome, Edge, or Brave. That one feature isn't available in Firefox or Safari yet. Browse all versions →
zddc-server defaults. The schemas above are deployment-agnostic — any of them is a valid tracking number. The zddc-server reference implementation ships the Basic schema by default (originator-project-discipline-type-sequence), plus the optional per-deliverable [suffix] (a hyphenated part marker such as -A for an appendix). Two deployment behaviours are worth knowing:
A sensible default profile. The schemas above are all valid tracking numbers; pick the one that fits your project. A common starting point is the Basic schema (originator-project-discipline-type-sequence), plus the optional per-deliverable [suffix] (a hyphenated part marker such as -A for an appendix). Two conventions are worth knowing:
archive/<party>/, the server sets originator from the party-folder name and renders it read-only — the folder is its single source of truth, so it can't drift from where the deliverable is filed..zddc configuration.originator matches that folder's name — the folder is the single source of truth, so the code can't drift from where the document is filed.A ZDDC project mirrors the natural lifecycle of an engineering deliverable: drafted in private, lined up for issue, formally exchanged, kept as record. Each canonical folder maps to one of those stages, so file location alone tells you where a document is in its lifecycle. An operator only needs to create one file — a .zddc in an empty directory — and the rest of the layout populates as work happens.
A ZDDC project mirrors the natural lifecycle of an engineering deliverable: drafted in private, lined up for issue, formally exchanged, kept as record. Each folder maps to one of those stages, so file location alone tells you where a document is in its lifecycle. You only create the folders you need, when you need them.
Mechanics: folders materialise on first write, names match case-insensitively, the WORM zones (received/, issued/) enforce write-once via an ACL mask, and the six top-level aggregators (ssr/mdl/rsk/working/staging/reviewing) are virtual — they never materialise on disk but show up in listings, computed from archive/<party>/… at request time. Mkdir at the project root is restricted to archive + system names (_/.-prefixed) so the virtual names can never be shadowed by a physical folder. Drop files where the lifecycle says they go and the layout takes care of itself.
The in-flight ratchet. working/ → staging/ → issued/ is a one-way handoff. project_team iterates freely in working/ (the auto-own-fenced subfolder gives each user a private rwcda workspace). When they drop a file into staging/ their access downgrades to cr — they can drop more, but only the document_controller can change what's already there. When DC publishes to issued/, the WORM mask downgrades even DC to cr (write-once). Each handoff is a commitment by permission-loss.
How it flows. working/ → staging/ → issued/ is a one-way progression: your team drafts freely in working/, lines finished files up in staging/ for the document controller to sign off, and the document controller publishes the package into issued/ as the permanent record. Treat received/ and issued/ as write-once — once a document lands there, it stays exactly as filed.
5-step transmittal workflow:
@@ -1133,156 +1090,21 @@ project/Submittals from counterparties (tracking numbers containing -SUB- at status IFR or IFA) require a response transmittal whose status starts with RS (RSA, RSB, RSC, …). The flow walks the ratchet:
Submittals from counterparties (tracking numbers containing -SUB- at status IFR or IFA) require a response transmittal whose status starts with RS (RSA, RSB, RSC, …). The flow follows the same lifecycle:
archive/<party>/received/<tracking>/ and pick Plan Review. The server scaffolds a workflow folder at archive/<party>/reviewing/<tracking>/ — its .zddc carries a received_path pointer back to the canonical submittal and a planned response date.archive/<party>/working/<your-email>/ is where reviewer notes and the response payload are drafted. The reviewing/ virtual aggregator at the project root surfaces all open reviews across parties.working/ into archive/<party>/staging/ for sign-off. Project team's permission on staged files downgrades to cr — the doc controller takes over.staging/ into archive/<party>/issued/ via the standard 5-step transmittal flow. The reviewing scaffold is deleted at issue time.received/, start a review folder under reviewing/ that points back to it, so every open response is in one place.working/.staging/ for the document controller to sign off.staging/ into issued/ via the standard 5-step transmittal flow.A fresh zddc-server deployment grants no access to anyone until two config files are populated. Without them the server runs but every request returns 403. The embedded defaults ship with empty role members, so deployments must opt-in to authorize anyone — there is no default "anything goes" mode (except --insecure, which is explicitly for deliberately-public archives).
Two files, both named .zddc. YAML format. Hand-edited.
/.zddcAt <ZDDC_ROOT>/.zddc, name at least one admin:
admins: is honored only at the root file. Admins behave as normal users by default and elevate per-request via the zddc-elevate=1 cookie (the header toggle visible in every tool) or implicitly when authenticating with a bearer token. This sudo-style model means an admin can't accidentally clobber files in their everyday browsing — elevation is opt-in.
Without this file the server refuses to start (the served tree would be publicly accessible to anonymous callers); pass --insecure to acknowledge a deliberately-public deployment.
<project>/.zddcIn each project, populate role members:
- -That's it. The embedded cascade does the rest:
- -project_team gets read across the project plus the in-flight ratchet (cr in working/ + reviewing/ + staging/, with rwcda inside each user's auto-own-fenced home under working/).document_controller creates party folders at archive/; when they do, the auto-own .zddc written at archive/<party>/ grants both their email AND the document_controller role rwcda — so any DC in the role has full authority at every party a peer created. Explicit rwcd grants at incoming//staging/ for the QC + transfer workflows, and WORM cr at received//issued/ for write-once filing.observer is pure read-only across the project — intended for external auditors, regulators, and read-only viewers who must not contribute content.A DC is typically also a project team member (the *@burnsmcd.com glob catches them). The embedded defaults restate document_controller: rwcda at every slot that grants project_team a narrower verb — within-level union of all matched principals gives DCs rwcda ∪ cr = rwcda, preserving full authority. Document controllers are not subtree-admins anywhere. Their power comes purely from cascade grants; admin elevation is reserved for the root admins: list (the human escape hatch).
Add a new project team member with one line; revoke by removing the line. No need to restate the cascade's grants — they're already in the embedded defaults that ship with zddc-server.
| Key | -Where | -Shape | -
|---|---|---|
admins: |
- Root only | -List of emails. Sudo-style; gates on zddc-elevate=1. |
-
acl: |
- Anywhere; cascades | -{ permissions: { <principal>: <bits> }, inherit: <bool>? } |
-
roles: |
- Anywhere; members union across the cascade | -{ <name>: { members: [...], reset: <bool>? } } |
-
title: |
- Per-project only | -String; surfaces on the landing-page picker. | -
Permission bits — any subset of:
- -r readw write (overwrite existing files)c create (new files, new directories)d deletea admin (modify the .zddc ACL at this level — distinct from the root admins: list, which is the elevation-bypass sudo channel)An empty bits string ('') is an explicit deny.
Principals — three forms:
- -@, e.g. alice@burnsmcd.com'*@acme.com' (quote it in YAML so the leading * doesn't confuse the parser)@, e.g. document_controller. The role's members are looked up via roles: at any cascade level.This is silently dropped:
-The YAML parses cleanly but ACLRules only reads permissions:. The allow: block is discarded during unmarshal and you end up with zero grants. Correct form:
zddc-server prints a startup warning when the root .zddc grants nobody anything — watch for it on first boot:
To dump the full annotated schema (every cascade key with documentation):
- -That prints the embedded defaults.zddc.yaml with comments explaining every option (worm:, auto_own:, auto_own_roles:, auto_own_fenced:, drop_target:, apps:, convert:, records:, available_tools:, default_tool:, dir_tool:, and more). Pipe it to a file and use it as the starting point for any deeper customization.
Single-file HTML applications — each is complete and self-contained. Save one locally and it works forever, without internet, without updates, without a subscription. None of them require any configuration to run; .zddc files and zddc-server only add to them. Together they cover the full ZDDC workflow: browse to look at anything; classify to name incoming files and build transmittals; archive to search and export the formal record.
Single-file HTML applications — each is complete and self-contained. Save one locally and it works forever, without internet, without updates, without a subscription. None of them require any configuration to run; optional .zddc files only add to them. Together they cover the full ZDDC workflow: browse to look at anything; classify to name incoming files and build transmittals; archive to search and export the formal record.
Local directory access relies on the Chromium-based browser File System Access API. It does not work in Firefox or Safari. Run the tools through zddc-server for any browser, network access, and ACL enforcement.
To open a folder directly from your computer, use a Chromium-based browser — Chrome, Edge, or Brave. That feature relies on the browser's File System Access API, which Firefox and Safari do not yet support.