162 lines
4.2 KiB
Markdown
162 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. |
|