Skip to content

Decisions

The architecture decisions (ADRs) of Nereus, one file per decision, each opening with an "In short" block. The format and the rule for numbers are in ADR 0001.

Decision Status In short
0001. Record architecture decisions Accepted Every architecture decision is recorded in docs/adr/, one file per decision in Nygard's format. A number is valid only once its ADR is merged into main.
0002. Conceptual model: reef, Instance, Mandate, Nereid, Tool Proposed The platform is five layers plus Vendor: reef, Instance, Mandate, Nereid and Tool. A reef is a capability, an API group, and may exist with no Nereid.
0003. nereus init prepares the platform; reefs and Nereids are added at runtime Proposed nereus init prepares a cluster with the built-in core reef and a profile's reefs; every other capability arrives later as a reef, with Nereids added at runtime. What init installs is revised by ADR 0014.
0004. Reefs and their Nereids extend the CLI with their own commands Proposed Each reef describes its commands as data published in status, and the CLI builds them at runtime, grouped by reef, never by Nereid or Tool.
0005. One writer per field Proposed The API writes spec; each Nereid writes only its own part of status. A field that needs two writers is split.
0006. Authentication is a reef Proposed authentication is a reef: logins are always OIDC, the platform proves itself outwards through a Mandate per identity, and the User belongs to core.
0007. Public by design Accepted The project is Apache-2.0 and public by design: no identifying data in any commit, and public names chosen as if already public.
0008. The CLI is written in Python, with uv and typer Accepted The CLI is written in Python, managed with uv, with typer for commands and the official kubernetes client.
0009. Each reef is an API group <reef>.getnereus.dev Proposed Each reef is its own API group <reef>.getnereus.dev, starting at v1alpha1; the platform's own kinds live in core.getnereus.dev.
0010. Reefs are added at runtime; commands are grouped by reef Proposed A reef is added at runtime from its contract, and a Nereid is added on its own and looks after one or more reefs. The release reef has four kinds.
0011. Reefs, Nereids and Mandates, managed with top-level commands Proposed Reefs, Nereids and Mandates are managed with top-level commands, with --reef and --nereid as the flags everywhere; a Mandate binds one reef to one Nereid.
0012. Every error message says what happened and how to fix it Proposed Every error message, from the CLI or a Nereid, follows eight rules: what happened, the cause, how to check, how to fix, what changed, no traceback, and a fitness function.
0013. Command conventions Proposed Commands share one shape, nereus <noun> <verb> <name>, with kubectl's verbs, dry runs, examples, and refusals that list the commands to run.
0014. Profiles Proposed Core is only the engine; a profile lists the reefs, Nereids and Mandates to install, run as the commands a person would type. It revises what nereus init installs (ADR 0003).
0015. Tenancy Proposed Tenancy is a reef whose kinds come from each instance, with one fixed shape: every kind is a tree node with an optional parent, and one kind is the boundary.
0016. The catalog reef Proposed A catalog reef holds two kinds split by lifecycle, Workload for what runs and Package for what is published, with three characteristics and configurable types.
0017. Resource reefs Accepted Five resource reefs, each a small contract kind per family, with the provider chosen in the Mandate and a Mandate selected by its match.
0018. The Nereus API is the one door Proposed The Nereus API is the one door of the platform: clients talk to it with the person's token, and the Kubernetes API stays behind it.
0019. The messaging reef Proposed The conversation joins the messaging reef as records (Thread, Order, Claim, Message), with a bus behind a Nereid.
0020. The delivery reef Proposed A delivery reef with one kind, Delivery, takes a Workload to an Environment; the Nereid, never the client, resolves an image tag to a digest.
0021. The registry reef Proposed A registry reef with Registry and Repository kinds; images are read with one read-only credential per Registry, over TLS, and published through the platform.
0022. A reef adds a screen to the portal as a Web Component its Nereid serves Accepted A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract, loaded at runtime.
0023. An external registry's push credential is the Repository's secret Proposed An external registry's push credential is the Repository's secretRef, read by the Nereid through a SecretBinding, never on the person's machine.
0024. The scm reef Proposed An scm reef holds what a source host is to Nereus: a Connection names an organisation, reached through the App its scm Mandate names, and a Mirror copies a repository.
0025. The platform receives metrics from anywhere through the CLI and the Nereus API Accepted Metrics enter only through the Nereus API, with the CLI as the official client: declared sources, a spool, late-send alerts with a heartbeat, and machine identities.
0026. The environment reef Proposed The environment reef has one kind, Environment, which is only the request; the cluster kept for it is naxos.
0027. Teams Accepted A role is bound to a team, a position or a User on a node of the tenancy tree, and the Nereus API asks before it acts. Access roles, teams and Users are kept apart.
0028. The presentations reef Accepted The presentations reef keeps the deck as a Presentation and each time it is given as a Session.
0029. A reef declares its MCP tools in the Nereid contract Proposed MCP is a door of the Nereus API, not a reef: each reef declares its MCP tools in its Nereid contract, and the API serves them at /mcp.
0030. Triton is the messaging reef's Nereid of rooms and peers Proposed Triton is the messaging reef's Nereid of rooms and peers, an internal service reached only through the Nereus API.