About this document
This document follows the arc42 template for the publication surface at policy.coulomb.social. It is the first-wave architecture document this repository is allowed to author. Other first-wave systems are written in their owning repos.
01Introduction and Goals
Policy Nexus exists so estate canon and architecture decisions have a permanent, current, addressable public home. Before this system, governing documents were served from disposable artifact URLs.
1.1 Requirements Overview
- Publish canon (
standards,architecture,constitution) and per-repo ADRs from the repositories that own them. - Keep one stable current URL and one immutable revision URL per document (ADR-0001).
- Fail closed when a source disappears or an immutable revision would change.
- Show status, owner, revision, and review currency on every page.
1.2 Quality Goals
- Permanence of published addresses.
- Honesty about staleness.
- Source-of-truth stays upstream — this system never writes back.
- Builds are deterministic and stdlib-only.
1.3 Stakeholders
| Role | Concern |
|---|---|
| the-custodian | What counts as canon; ratification. |
| Source-repo owners | Their document is published accurately. |
| railiance-platform / rapp-policy-nexus | Substrate, Helm, promotion. |
| Readers inside and outside the estate | A URL that still resolves. |
02Architecture Constraints
N/A for this stub — first-wave complete will record stdlib-only rendering, single-node rail availability, and the no-CMS rule.
03System Scope and Context
In: addressing, rendering, currency, the public static site. Out: ratification, legal advice, regulatory intake (risk-nexus), editing surfaces, search.
3.1 Business Context
Source owners publish governing documents. This system makes those documents findable and durable. It does not decide what is current canon.
3.2 Technical Context
- Inputs:
publication.json, sibling or fetched git checkouts,source-inventory.json. - Outputs: static HTML,
publication-manifest.json, an OCI image. - Neighbours: owning source repos, Forgejo Actions,
rapp-policy-nexus,railiance-apps, the reef Traefik/cert-manager substrate.
04Solution Strategy
N/A for this stub — pull-on-schedule ingestion, explicit manifest entries, stdlib renderer. To be written as first-wave complete.
05Building Block View
5.1 Level 1 – System/Top-Level
N/A for this stub — builder, inventory auditor, currency checker, OCI artifact, Helm package in rapp-policy-nexus.
5.2 Level 2 – Key Components
N/A for this stub.
5.3 Level 3 – Internal Structure (as needed)
N/A for this stub.
06Runtime View
N/A — the published site is static files. Daily source-pull and promotion are operational scenarios for a later revision.
07Deployment View
N/A for this stub — see WP-0001-T04. Single-node restart recovery, not a high-availability SLA.
08Cross-Cutting Concepts
N/A for this stub.
09Architecture Decisions
| Id | Status | Decision | Source |
|---|---|---|---|
policy-nexus-adr-0001 | accepted | Stable current address + immutable revision address; no deletion | docs/adr/ADR-0001-addressing-and-permanence.md |
Later publish ADRs from WP-0003 land here. local and unresolved conflict rows do not.
10Quality Requirements
N/A for this stub — currency failure is already a build/CI failure.
11Risks and Technical Debt
N/A for this stub. Known residual: Markitect arc42-v1 schema is not registered yet (WP-0002-T02).
12Glossary
| Term | Meaning |
|---|---|
| Current address | The stable URL for the document as it now stands. |
| Revision address | Write-once URL for one source digest. |
| Publication entry | One object in publication.json. Discovery is not publication. |
| First-wave complete | Chapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A. |