Architecture Decision Records
ADRs record architectural decisions: the context they were made in, the alternatives that were rejected, and the consequences accepted. An ADR’s Status field tracks the decision through its whole lifecycle, from proposal to implementation.
When to write one
Section titled “When to write one”Write an ADR for decisions that shape architecture across multiple PRs, are expensive to reverse, or reject a plausible alternative someone will re-propose later. Routine implementation choices don’t need one.
Format
Section titled “Format”One file per decision in this directory, named NNNN-short-title.md with a
monotonically increasing number. Sections: Status, Context,
Decision, Consequences, Alternatives considered, plus an optional
References and appendices where they earn their keep.
Statuses: Draft, Proposed, Accepted, In Progress (implementation underway), Implemented, Superseded by ADR-NNNN. A superseded ADR is never edited to say something else — it gets a status pointer to its successor.
Draft is pre-decision working material: it records a design direction and open questions but is not yet ready for review as a proposed architecture.
| ADR | Status | Summary |
|---|---|---|
| ADR-0001 — Unified Permission Model | Proposed | One Role/RoleBinding model for all subject kinds (Users, Groups, ServiceAccounts, Controllers, Operators) on the generic resource API and token issuance, plus the crate structure that realizes it. |
| ADR-0002 — Generic Resource Subresource Execution Model | Draft | A typed registration and execution seam for stored, virtual, generated, streaming, and possible connection-oriented subresources. |
| ADR-0003 — Resource Families | Proposed | A named set of kinds sharing one name pool within a parent scope, listable and addressable as a unit — the grouping polymorphic listing and the extension-kind migration need. |
| ADR-0004 — Control-Plane Process Topology | Proposed | The resource API, admission, authorization, GC, and watch become a rise-apiserver process; everything else is a client over the HTTP contract with a Rise-issued token. Fixes the invariants, the gates, and the order the split happens in. |
| ADR-0005 — ECS Deployment Backend | In Progress | How Rise’s deployment model maps onto Amazon ECS (Fargate) and the surrounding AWS services: Traefik ingress behind an AWS load balancer, ECR pulls via the task execution role, SSM-injected secret env, and a sidecar-delivered workload identity contract. |
| ADR-0006 — Scoped CLI Sessions | Implemented (typed API) | CLI sessions narrowed to named projects and environments through ADR-0001’s authorization_details ceiling: permission names and presets, environment coverage via a governed rise.dev/environment label, requester-proposes/approver-decides device login, and one enforcement choke point on the typed API, carrying over to the generic resource API as kinds migrate. |