From 699069e538444f602bac817dd0a218a3605591fd Mon Sep 17 00:00:00 2001 From: ZDDC Date: Mon, 27 Apr 2026 12:38:30 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20add=20zddc-server.html=20=E2=80=94=20lo?= =?UTF-8?q?cal=20vs=20online=20mode,=20what=20the=20server=20adds?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The intro page's "zddc-server" link previously pointed at a Codeberg blob URL (which uses /src/branch/main/, not GitHub's /blob/main/, so the link 404'd anyway). Replace with a hand-edited concept page on the website itself. The page is structured around two access modes: - Local directory mode — open a tool, point it at a folder, work via the File System Access API. No upload, no server. - Online mode — take that same local directory and put it behind any web server (nginx, Caddy, Apache, even python -m http.server). The Archive Browser tool works against the server's directory listings the same way it works against a local folder. zddc-server is then introduced as a Go binary that gives you online mode out of the box, plus four conveniences a generic web server can't: ACL via .zddc YAML files (gated on email-header trust), virtual /.archive/ URL space, per-request access logging, and the mundane glue (TLS, ETags, conditional GET, CORS). Closing section: the on-disk layout is the same in both modes — the server doesn't transform the archive, it serves it. Stop the server and the directory is still a valid ZDDC archive. The "Zero Day" promise: server is convenience, not lock-in. Also: - Add Server nav link to website/index.html and reference.html. - Fix the bootstrap/README.md link that used GitHub's /blob/main/ pattern (Codeberg uses /src/branch/main/). - Update ARCHITECTURE.md doc-ownership table: new row for the concept page, clarify that zddc/README.md is the operations reference. Co-Authored-By: Claude Opus 4.7 (1M context) --- ARCHITECTURE.md | 5 +- website/index.html | 5 +- website/reference.html | 1 + website/zddc-server.html | 162 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 169 insertions(+), 4 deletions(-) create mode 100644 website/zddc-server.html diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 36e4088..dcc6f8f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -61,8 +61,9 @@ Each topic has exactly one authoritative home; everything else links to it. |---|---|---| | What ZDDC is + tool channel links + install bundles | `website/index.html` (hand-edited intro for `zddc.varasys.io/`) | repo `README.md`, `bootstrap/README.md` | | File-naming convention spec (status codes, modifiers, folder format) | `website/reference.html` | repo `README.md`, in-tool help text | -| Customer-deployment install (install.zip, level-1/2 stubs, `?v=`, audit) | `bootstrap/README.md` | website intro, `zddc/README.md` | -| zddc-server config, ACL, `.archive`, deployment | `zddc/README.md` | `AGENTS.md`, `bootstrap/README.md` | +| Local-mode vs online-mode concept; what `zddc-server` adds | `website/zddc-server.html` | website intro | +| Customer-deployment install (install.zip, level-1/2 stubs, `?v=`, audit) | `bootstrap/README.md` | website intro, `zddc/README.md`, `zddc-server.html` | +| zddc-server operations: env vars, ACL syntax, `.archive` URLs, container vs binary | `zddc/README.md` | `AGENTS.md`, `bootstrap/README.md`, `zddc-server.html` | | Build / release / channel commands | `AGENTS.md` | repo `README.md` ("see AGENTS.md") | | Architecture & internal patterns | `ARCHITECTURE.md` (this file) | `AGENTS.md` | | Per-tool internal design quirks | `/README.md` | (linked from website intro tool cards) | diff --git a/website/index.html b/website/index.html index 226aa80..bb5c316 100644 --- a/website/index.html +++ b/website/index.html @@ -69,6 +69,7 @@ Docs + Server @@ -168,7 +169,7 @@ -

See bootstrap/README.md for the install model, the per-project / per-tool override pattern, and the audit grep that lets you see what every project on a deployment is pointing at.

+

See bootstrap/README.md for the install model, the per-project / per-tool override pattern, and the audit grep that lets you see what every project on a deployment is pointing at.

@@ -176,7 +177,7 @@
  • Technical Reference — the full ZDDC convention: filename format, tracking numbers, revisions, status codes, folder naming, transmittal workflow.
  • codeberg.org/VARASYS/ZDDC — source code, issue tracker, contributor docs.
    • -
  • zddc-server — optional Go HTTP server for serving a ZDDC archive with ACL and a virtual .archive index.
    • +
  • zddc-server — how the local-mode and online-mode tools relate, and what the optional Go HTTP server adds (access control, virtual archive index, audit logging).
diff --git a/website/reference.html b/website/reference.html index 851d293..49ee2b2 100644 --- a/website/reference.html +++ b/website/reference.html @@ -57,6 +57,7 @@ Docs + Server diff --git a/website/zddc-server.html b/website/zddc-server.html new file mode 100644 index 0000000..f527493 --- /dev/null +++ b/website/zddc-server.html @@ -0,0 +1,162 @@ + + + + + + zddc-server — Zero Day Document Control + + + + + + + + + + + + + + +
+
+ + + ZDDC + + +
+
+ + +
+
+

zddc-server

+

ZDDC has two access modes over the same on-disk archive. Online mode is what you get when you put a local directory behind a web server. zddc-server is an optional Go binary that adds access control, a virtual archive index, and audit logging on top.

+
+
+ +
+ +
+

Two modes, one archive

+ +
+
+

Local directory mode

+

Open a tool, click Add Directory, point it at a folder. The tool reads files directly 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).

+
+
+

Online mode

+

Take the same local directory and put it behind any web server (nginx, Caddy, Apache, even python -m http.server). The Archive Browser tool talks to the server's directory listings instead of the local filesystem.

+

Read-only, no special server software, works in any browser.

+
+
+ +

That's it. Same on-disk layout, two access mechanisms. The convention is the contract; the mode is an access decision.

+
+ +
+

What zddc-server adds

+

zddc-server is a small Go binary built specifically to serve ZDDC archives. It is a web server, so it gives you online mode out of the box — but it adds things a generic web server can't:

+ +
    +
  • If the server reads email headers, it can enforce access control. Behind any reverse proxy that authenticates users (Authelia, oauth2-proxy, your own SSO) and sets an X-Email request header, zddc-server consults .zddc YAML files in directories. Cascading bottom-up; deeper rules override shallower ones. No database, no admin UI — edit the files with any text editor.
    • +
  • Virtual .archive URL space. GET /Project/.archive/123-XYZ.html resolves to the canonical revision file (the one in the chronologically earliest transmittal that contains it). Computed from filenames at request time — no cache, no separate index file. Restart the server and it rebuilds.
    • +
  • Per-request access logging keyed to the authenticated user's email — method, path, status, bytes, duration.
    • +
  • TLS, ETags, conditional GET, CORS, autoindex. The mundane glue that makes a directory pleasant to serve.
    • +
+ +

In short: any web server can do online mode for reads. zddc-server adds ACL, a virtual archive index, and audit logging while remaining a thin wrapper around the same directory.

+
+ +
+

Still just files in folders

+

The on-disk layout is the same whether you access locally or online. The server doesn't transform the archive — it serves it. Stop the server and the directory is still a perfectly valid ZDDC archive that opens in local-directory mode.

+ + 
ZDDC_ROOT/
+  index.html           ← landing tool
+  archive.html         ← archive browser
+  transmittal.html
+  …
+  Project-001/
+    .zddc              ← ACL (optional, YAML)
+    2025-10-31_123456-EM-MDL-0001 (IFR) - Master Deliverables List/
+      123456-EM-MDL-0001_A (IFR) - Master Deliverables List.pdf
+    2025-11-12_123456-EL-SPC-2623 (IFR) - Specification For Switchgear/
+      123456-EL-SPC-2623_A (IFR) - Specification For Switchgear.pdf
+  Project-002/
+    …
+ +

This keeps the "Zero Day" promise: the server is convenience, not lock-in. Walk away from zddc-server tomorrow and the archive is still a perfectly valid convention-named folder tree, fully usable with nothing more than a file manager.

+
+ +
+

Get it

+

The server lives at codeberg.org/VARASYS/ZDDC under zddc/. Operations and configuration — environment variables, TLS modes, the .zddc ACL syntax, the virtual archive index URL patterns, container vs native binary deployment — are documented in zddc/README.md.

+ +

Quick start (with podman available):

+ 
git clone https://codeberg.org/VARASYS/ZDDC.git
+cd ZDDC/zddc
+ZDDC_DATA_DIR=/path/to/your/archive podman-compose up --build
+ +

For the deployment-side install of the tools onto a zddc-server instance — including the level-1/level-2 bootstrap pattern, install.zip, and the channel-tracking track-*.zip bundles — see bootstrap/README.md.

+
+ +
+ + + + + + +