coulomb/policy-nexus
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
policy-nexus/docs/architecture/policy-nexus_v0.1.md
tegwick a8fb62a3bc 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.
2026-08-18 22:16:02 +02:00

4.2 KiB
Raw Blame History

id title status owner revision version last_reviewed review_interval
policy-nexus-architecture Policy Nexus architecture proposed the-custodian draft-1 0.1 2026-08-18 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.