Constitution - Stackra

The constitution holds the rules that do not bend. An ADR may refine a law. It may never contradict one. Changing a law is itself an ADR that supersedes the law’s previous text, and the law page is updated in the same commit.

Law	Governs
Boundaries	tiers, dependency direction, placement, no literals in shared packages
Secrets	where secret values live, who sets them, what agents may not do
Security	authenticated principal, server-side authorization, audit, data classification
HTTP and events	API shape, idempotency, errors, ids, event envelope
Tenancy	two-layer tenant isolation, isolation tests, the Pro scope tree
Delegation	who decides, how work is handed to agents, git discipline

How the hierarchy works

Laws

This tab. Short, normative, rarely changed.

ADRs

Record one decision each and apply or refine a law. Where an ADR and a law disagree, the law wins and the ADR is wrong.

Standards and guides

Standards are operating rules for one kind of member. Guides say how to do a task. Both follow the laws.

A law names its check

A rule with no check is a comment. Every law below states its enforcement in one of three words:

Word	Meaning
Enforced	A check exists in this repository and runs in `pnpm verify`, a git hook, an agent hook or CI. The page names it.
Partial	Some of the rule is checked. The page says which part is not.
Planned	No check yet. The page names the mechanism. Until it lands, a reviewer refuses a violation by hand.

A law whose check is planned is still a law. Never lower a rule to make a gate pass: fix the code, or change the law through an ADR.

Standing principles

Reviewers cite these by name. Each is an application of one of the laws or ADRs and is not a separate rule.

Principle	Statement	Where it lives
A service is a runtime boundary	A service is a unit of deployment, not a unit of business meaning.	Boundaries
Dependencies point one way	`config` → `lib` → `app` and `service`; apps and services are peers that never import each other; nothing points back.	ADR 0003
Core is meaning	A package’s core layer states what the package is about. It never depends on transport, an ORM, a driver or a UI toolkit.	ADR 0004
The layer that needs an abstraction owns its port	A port lives in `application`, never in `infrastructure`.	ADR 0004
Presentation owns delivery	API, React, web and native are delivery surfaces of one package, not separate business layers.	ADR 0004
Generated artifacts are never the source of truth	Decorated classes and hand-written source are authoritative. Generated code is regenerated, never edited.	Standards
Shared packages hold mechanisms, apps hold definitions	A shared package never contains a product value.	Boundaries
Not built yet means not built	A rejected or deferred technology is not introduced “helpfully”.	ADR 0011

Amending a law

Write an ADR that states the new text, the reason and the enforcement. Use the ADR template.
Update the law page in the same commit and say which ADR changed it.
Update or add the check. If the check is planned, say so on the page.
Get a CODEOWNERS review.

Some pages in this tab describe a mechanism for a thing Stackra does not have yet, such as an Encore app or a tenant-owned table. They say so at the top. The law applies from the moment the thing appears, so the check must exist before it does.

History

2026-10-20, 0125: the dependency-direction principle follows 0003; “factories” became “mechanisms” (0094); the tenancy row names the Pro scope tree.

​How the hierarchy works

​A law names its check

​Standing principles

​Amending a law

​History

How the hierarchy works

A law names its check

Standing principles

Amending a law

History