tegwick
a8fb62a3bc
Add the owner-facing publication contract, a regenerable ADR review ledger, and publication entries for this repo's ADR-0001 plus the eight ready railiance-master ADRs.
161 lines
4.2 KiB
Markdown
161 lines
4.2 KiB
Markdown
---
|
||
id: policy-nexus-architecture
|
||
title: "Policy Nexus architecture"
|
||
status: proposed
|
||
owner: the-custodian
|
||
revision: "draft-1"
|
||
version: "0.1"
|
||
last_reviewed: "2026-08-18"
|
||
review_interval: 6m
|
||
---
|
||
|
||
# Policy Nexus — Software Architecture Documentation (arc42)
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## 1. Introduction 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
|
||
|
||
1. Permanence of published addresses.
|
||
2. Honesty about staleness.
|
||
3. Source-of-truth stays upstream — this system never writes back.
|
||
4. 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. |
|
||
|
||
---
|
||
|
||
## 2. Architecture Constraints
|
||
|
||
N/A for this stub — first-wave complete will record stdlib-only
|
||
rendering, single-node rail availability, and the no-CMS rule.
|
||
|
||
---
|
||
|
||
## 3. System 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.
|
||
|
||
---
|
||
|
||
## 4. Solution Strategy
|
||
|
||
N/A for this stub — pull-on-schedule ingestion, explicit manifest
|
||
entries, stdlib renderer. To be written as first-wave complete.
|
||
|
||
---
|
||
|
||
## 5. Building 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.
|
||
|
||
---
|
||
|
||
## 6. Runtime View
|
||
|
||
N/A — the published site is static files. Daily source-pull and
|
||
promotion are operational scenarios for a later revision.
|
||
|
||
---
|
||
|
||
## 7. Deployment View
|
||
|
||
N/A for this stub — see WP-0001-T04. Single-node restart recovery, not
|
||
a high-availability SLA.
|
||
|
||
---
|
||
|
||
## 8. Cross-Cutting Concepts
|
||
|
||
N/A for this stub.
|
||
|
||
---
|
||
|
||
## 9. Architecture 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.
|
||
|
||
---
|
||
|
||
## 10. Quality Requirements
|
||
|
||
N/A for this stub — currency failure is already a build/CI failure.
|
||
|
||
---
|
||
|
||
## 11. Risks and Technical Debt
|
||
|
||
N/A for this stub. Known residual: Markitect `arc42-v1` schema is not
|
||
registered yet (WP-0002-T02).
|
||
|
||
---
|
||
|
||
## 12. Glossary
|
||
|
||
| 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. |
|