ARCHITECTURE.adoc

Architecture

technical-notes is a documentation archive, not a software project: it holds short, citable technical notes (Markdown, optionally with a Typst source and rendered PDF) that are individually deposited on Zenodo with a DOI. There is no source code, no build system, and no runtime component.

Layout

.
├── README.md              # index of published notes (title, date, DOI)
├── <note-slug>.md         # note source (Markdown)
├── <note-slug>.pdf        # rendered note (optional, Typst-produced)
├── <note-slug>.typ        # Typst source for the PDF (optional)
├── docs/                  # process documentation (this file's siblings)
├── LICENSE / LICENSES/    # MPL-2.0 (repo tooling/process docs) +
│                          #   CC-BY-SA-4.0; individual notes carry
│                          #   their own licence at Zenodo-deposit time
└── .github/               # CI wrappers (governance, security scan)

The invariant

Every note listed in the README resolves to a real, citable Zenodo record. If that link breaks, the repo has failed at its one job.

Publishing flow

There is no runtime to diagram; the only “flow” is authorial:

draft note (.md [+ .typ -> .pdf])
        |
        v
   README table entry (title, date, concept DOI, version DOI)
        |
        v
   Zenodo deposit (direct API today; GitHub Release once the
   Zenodo-GitHub integration is enabled — see README § Zenodo archiving)

Out of scope

• No source code, package, or binary is built or shipped from this repo.

• No API, service, or CLI.

• No automated test suite — there is no code to exercise.

See also

• docs/usage.adoc — how to cite a note.

• docs/contributing.adoc — how to add a new note.

• docs/decisions/ — ADRs, historical record of why this shape.