---
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. |