Start the arc42 contract and publish the first ADR set
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.
This commit is contained in:
parent
7a24e9107f
commit
a8fb62a3bc
34 changed files with 9669 additions and 28 deletions
161
docs/architecture/policy-nexus_v0.1.md
Normal file
161
docs/architecture/policy-nexus_v0.1.md
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
---
|
||||
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. |
|
||||
Loading…
Add table
Add a link
Reference in a new issue