Architecture decision records

Index of the significant decisions about the project, recorded in MADR style.

This directory records significant decisions about myriarch in MADR style. Each record states the context, the decision, its consequences and the alternatives that were considered.

Process

A new record copies the shared template 0000-template.md with the sections Status, Date, Related, Context, Decision, Consequences (Positive and Negative) and Alternatives considered.
It takes the next free four-digit number and is named NNNN-kebab-title.md.
Status values are Proposed, Accepted, Deprecated and Superseded by ADR-NNNN. A record whose decision is replaced only in part keeps its status and names the superseding record (“Superseded in part by ADR-NNNN” or “Accepted; … superseded by ADR-NNNN”).
Accepted records are not rewritten. A change of mind is a new record that supersedes the old one.
Editorial changes (links, typos, front matter) are allowed and do not change a decision.
Records are proposed via pull request with DCO sign-off (ADR-0019).

Records

The records 0001 to 0014 were written during early development, in German, inside the former architecture document. They were migrated to this directory with their original numbers and rewritten in English. Their date is 2026-10-07, the earliest date for which a record is available; the decisions themselves were taken before. The records 0015 and later were written as separate files.

Some early operational decisions were not kept as separate records. They are described in the reference text instead: one outbound proxy and CA setting for all connections, the layout of an artifact mirror without a URL template, Sigstore trust through a proxy or a TUF mirror, and configuration validation without starting the server are covered in the security model and the architecture. The early decision to sign releases with a long-lived key is superseded by ADR-0023.

ADR	Title	Status
0001	A single server binary carries all server functions	Accepted
0002	PostgreSQL for state, event bus and leader election	Accepted, refined by 0036
0003	GitOps is the source of truth; the UI operates within the Git frame	Accepted
0004	Server-side rendering to one content-addressed configuration per agent	Accepted
0005	Templating with double brackets and typed whole-expression evaluation	Accepted
0006	Version updates through exchangeable executors	Accepted
0007	Package offers in the upstream draft format with Sigstore bundles	Accepted, refined by 0046
0008	Kubernetes: supervisor and collector in one pod	Accepted, superseded in part by 0024 (own combined image) and refined by 0026
0009	Server-sent events for live UI updates	Accepted
0010	Standard ServeMux and hand-written DTOs with a contract test	Accepted
0011	No containers for local development and tests	Accepted
0012	Agent access through enrollment tokens	Accepted, refined by 0046
0013	Target version from the UI within the Git frame	Accepted, refined by 0046
0014	Binary updates in the pod through container mode	Accepted, refined by 0026
0015	Project name “myriarch” and naming scheme	Accepted, superseded in part by 0029 and 0050
0016	Trademark usage and protection of the project name	Accepted
0017	Repository hosting, maintainer identity and later move to a neutral organization	Superseded in part by 0029
0018	License: Apache-2.0 for code, CC-BY-4.0 for documentation	Accepted
0019	Contribution model: Developer Certificate of Origin, no CLA	Accepted
0020	English as the language of documentation and project communication	Accepted
0021	Publication gates and scope of the first release (v0.1.0)	Accepted
0022	White-label meaning and vendor-neutral examples	Accepted
0023	Keyless release signing with Sigstore	Accepted, superseded in part by 0029
0024	Container registry (ghcr.io) and published image set	Accepted, superseded in part by 0029
0025	Login without an enterprise identity provider: bootstrap admin	Accepted
0026	Collector version updates on Kubernetes	Accepted, refined by 0037
0027	Model Context Protocol (MCP) access: principles	Accepted, superseded in part by 0029
0028	Relationship to OpenTelemetry and path towards a foundation	Accepted, superseded in part by 0029
0029	Host the project in the GitHub organization “myriarch” from the start	Accepted
0030	REUSE compliance and third-party notices	Accepted
0031	Project website myriarch.dev with Hugo and Docsy, built from the repository and served as static files	Accepted
0032	Continuous integration on GitHub Actions with GitHub-owned, SHA-pinned actions and one aggregate check	Accepted, amended by 0033
0033	OpenSSF Scorecard as the only third-party action, and policy rules for the Scorecard and release workflows	Accepted
0034	Authenticode signing of Windows release artifacts by the SignPath Foundation, with a defined fallback and exceptions for v0.1.0, v0.2.0 and v0.2.1	Accepted
0035	Release workflow: tag-only, isolated jobs, keyless signing and provenance, verification before an immutable publication, and a frozen signing identity	Accepted
0036	Database schema compatibility and rollback	Accepted
0037	OpAMP Bridge agents are recognised and locked until the Operator integration	Accepted
0038	Dependency license policy: a tripwire on the CNCF allowlist for pull requests, a narrower allowlist for releases	Accepted
0046	Host installation from the server: versions, artifacts and the installer bundle as data, integrity anchored on the host	Accepted
0050	Tagline backed by the documentation	Accepted

The Status column names the later records that refine, amend or supersede an earlier record; for example, ADR-0024 supersedes the “own combined image” aspect of ADR-0008 for published artifacts, and ADR-0026 refines ADR-0008 and ADR-0014 (gitops-pr as the Kubernetes default, container mode as an opt-in).

0034. Authenticode signing of Windows release artifacts by the SignPath Foundation, with a defined fallback and exceptions for v0.1.0, v0.2.0 and v0.2.1

Decision record 0034 (Accepted).

0035. Release workflow: tag-only, isolated jobs, keyless signing and provenance, verification before an immutable publication, and a frozen signing identity

Decision record 0035 (Accepted).

0046. Host installation from the server: versions, artifacts and the installer bundle as data, integrity anchored on the host

Decision record 0046 (Accepted).

0050. Tagline backed by the documentation

Decision record 0050 (Accepted).