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