Technical Reference

1. Overview

ZDDC — Zero Day Document Control — is an information management convention built on two rules:

• File naming — every deliverable filename encodes its tracking number, revision, status, and title. This makes each file self-describing and independently searchable without opening it.
• Folder naming — transmittal folders follow the same convention, date-prefixed so they sort chronologically and can be searched by the tracking numbers of the deliverables they contain.

Together, these two rules mean a plain folder on any shared drive becomes a fully searchable, auditable information management system. No server, no database, no software required to read the archive.

Because every deliverable is self-describing — its identity, revision, and status encoded in the filename itself — the convention works across organisational boundaries without requiring a shared platform. A project adopting ZDDC can extend the same convention to its clients, subcontractors, vendors, and any other party in the project ecosystem. Each party maintains their own archive; the shared naming convention makes every archive mutually intelligible. Adoption can be voluntary or contractually required. The result is a globally scalable, distributed information management system built on nothing more than agreed file naming and standard directory structures.

The tools below implement interfaces around this structure — but they're optional. The structure works without them, and any party can participate using only their file browser.

2. Filename format

The ABNF-like grammar below is a formal machine-readable definition of the filename format — primarily useful for parsers and AI systems. The human-readable explanation of each field follows in the sections below.

Rules:

• Tracking number: no spaces, no underscores, hyphens as separators only
• Underscore _ separates tracking number from revision
• Revision: no spaces; may include ~ prefix and/or + modifier
• Space before (status)
• Space-dash-space - before title
• Extension is the original file extension, preserved exactly

Anatomy (from left to right):

Real examples:

3. Tracking numbers

A tracking number is a deliverable's permanent identifier. It never changes — regardless of revision, status, or content changes. Think of it like a passport number: your name can change, your passport number doesn't.

No spaces, no underscores — hyphens as separators only. Format is yours to define; it must be consistent within the scope it covers.

Field definitions (in order)

Tracking numbers are composed of the following fields, in order:

• originator — Organizational unit responsible for the deliverable
• project — Project identifier; a recognizable placeholder is used for corporate-scope deliverables
• [phase] — Optional phase code (e.g., ECI, EPC)
• [area] — Optional area/budget code
• discipline — Engineering or functional group (e.g., EL, ME, CV, PM)
• type — Document category within discipline
• sequence — Zero-padded integer
• [suffix] — Optional hyphenated suffix for appendices or sheets

Schema rules

Choose the schema that matches your structure. The fields within brackets [ ] are optional and must be omitted consistently across all tracking numbers when not used.

Discipline codes

Discipline codes identify the engineering or functional group responsible for the document. They are defined per project and should be documented in the Master Deliverables List.

Type codes

Type codes identify the document category within a discipline. Type codes are scoped per discipline — the same code may mean different things in different disciplines.

Rule: Avoid ambiguity. On multi-discipline projects, type codes with overlapping meanings should be avoided or a cross-discipline registry should be agreed upon and documented.

Sequence numbers

Sequence numbers make the tracking number unique given all the preceding fields. Use zero-padded integers (e.g., 0001, 0042).

A suffix separated by a hyphen can denote appendices or sheets that are structural parts of the same deliverable:

4. Revisions

The revision field indicates the iteration stage of the deliverable. It consists of an optional ~ draft prefix, a base revision, and an optional + modifier.

Base revision types

Base revisions are one of three types: letter revisions (A, B, C...), number revisions (0, 1, 2...), or date-based revisions.

Letter revisions (design/review phase)

Letter revisions are used during the design and review phase. They sort lexically, so A < B < C, etc.

Number revisions (construction/record phase)

Number revisions are used after approval, typically at the Issued For Construction (IFC) stage. They sort lexically after letter revisions.

Date-based revisions

Date-based revisions apply to documents that are updated in place under a single permanent tracking number, where the date of the revision is the most meaningful piece of information a reader needs.

Rule: Two use cases for date-based revisions:

1. Recurring documents — issued on a fixed cadence (e.g., meeting minutes). The tracking number is fixed; the revision identifies which occurrence.
2. Living documents — issued on demand (e.g., schedules, risk registers). The tracking number is fixed; the revision indicates freshness.

Rule: Contra-indication. Documents that get a new tracking number each period (e.g., monthly progress reports where each month is a distinct deliverable) use normal letter and number revisions, not date-based revisions.

Date-based revisions sort lexically in the correct chronological order — your file browser will list them in date order when sorted by name.

5. Draft prefix (~)

The ~ prefix indicates a working draft, not yet formally issued.

Examples:

6. Revision modifiers (+)

Revision modifiers associate a file with a base revision without incrementing the revision. Used for comments, backup material, native source files, and quality records. Sorts after the base revision in alphabetical order.

The number after the modifier letter — +C1, +C2, and so on — is simply a sequence counter for uniqueness. If two reviewers each return a separate set of comments, they become +C1 and +C2. The same applies to all modifiers: the number distinguishes multiple files of the same type attached to the same revision.

Modifier table

7. Status codes

Status codes indicate the approval or review state of a deliverable. They appear in parentheses in the filename.

Primary status codes (closed set)

Primary status codes are used on formally issued deliverables. The status field in a draft filename shows the intended status when issued.

Rule: No DFT status. Draft status is not encoded as a status field. It is indicated by the ~ prefix on the revision, and must also be physically marked in the file itself (e.g., a DRAFT watermark or stamp).

Review status codes (closed set)

Review status codes are used as the status on +C (client or reviewer comments) and +Q (internal quality check) files. They record the outcome of the review — what the reviewer concluded and what action is required on the base document.

Typical review cycles

8. Folder naming

Transmittal folders follow the same convention as filenames — date-prefixed so folders sort chronologically:

Format: YYYY-MM-DD_trackingNumber (status) - title

Two tracking numbers in play

Two tracking numbers are always in play:

• Deliverable tracking number — embedded in each filename; permanent; unchanged across all packages it ever travels in
• Submittal package tracking number — in the folder name; reused by the response (same number, different date/status/optionally different title); a resubmittal gets a NEW tracking number

Submittal, response, and resubmittal rules

The status on a package folder is the lowest review outcome across all deliverables inside it. It summarises the package; it does not override the outcome of any individual deliverable.

Tracking individual deliverables

Search the deliverable's own tracking number across all transmittal folders in issued/ and received/. Every folder containing that number is part of its history: which package first carried it, what the response was, which resubmittal carried the revision, and what the final outcome was.

9. Project layout & transmittal workflow

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.

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.

5-step transmittal workflow:

Drafting a response transmittal

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:

1. Right-click the submittal in 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.
2. The party's working subfolder under 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.
3. When the response is ready, files move from working/ into archive/<party>/staging/ for sign-off. Project team's permission on staged files downgrades to cr — the doc controller takes over.
4. The doc controller cuts the package from staging/ into archive/<party>/issued/ via the standard 5-step transmittal flow. The reviewing scaffold is deleted at issue time.

10. zddc-server bootstrap

Two files, both named .zddc. YAML format. Hand-edited.

Step 1 — root /.zddc

At <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.

Step 2 — per-project <project>/.zddc

In 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.

Schema essentials

Permission bits — any subset of:

• r read
• w write (overwrite existing files)
• c create (new files, new directories)
• d delete
• a 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:

• Email address — must contain @, e.g. alice@burnsmcd.com
• Email glob — wildcard on the local part, e.g. '*@acme.com' (quote it in YAML so the leading * doesn't confuse the parser)
• Role name — anything without an @, e.g. document_controller. The role's members are looked up via roles: at any cascade level.

Common footgun

Verifying the bootstrap

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.

11. Tools

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.

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.