Architecture decisions

Each ADR records one decision, its context, consequences and the check that enforces it. An accepted ADR is not rewritten: a later ADR supersedes it, in the same commit, and the old page points forward. Format and status vocabulary: template.

ADR	Decision	Status
0001	Monorepo layout, catalogs and tooling	Accepted
0002	Documentation on Mintlify in `apps/docs`	Accepted
0003	Tier dependency direction	Accepted
0004	Package archetypes and layers	Superseded by 0126
0005	DI container and legacy decorators	Accepted, amended by 0143, 0145
0006	Naming, exports and imports	Accepted, amended by 0128
0007	Source documentation standard	Accepted, amended by 0128
0008	Test placement	Superseded by 0022
0009	Secrets: two mechanisms	Accepted, amended by 0257
0010	Services are independent workspace members	Accepted
0011	Rejected and deferred technologies	Accepted
0012	Code host and CI	Accepted
0013	Versioning and release	Superseded by 0025
0014	Data ownership and ORM	Accepted
0015	Contract packages	Superseded by 0117
0016	`.agents/` is the source of truth	Accepted
0017	Agent roster and models	Accepted
0018	Framework design record	Proposed
0019	Supply chain hardening	Proposed
0020	Observability and crash reporting	Proposed
0021	AI engine and agent write safety	Proposed
0022	Tests live in `__tests__` folders	Accepted
0023	Stackra is a framework; products consume it	Accepted
0024	MIT license, with stated exclusions	Accepted
0025	Packages publish to `npm.figentra.com`; every package builds to ESM dist	Accepted
0026	Turborepo remote cache self-hosted on Cloudflare R2	Accepted
0027	Every CLI the repo needs is pinned in mise	Accepted
0028	Package categories appear with their first package	Accepted, amended by 0127
0029	Encore.ts as one application under `services/`	Superseded by 0075
0030	Encore Cloud into the owner’s AWS; four environments	Proposed
0031	Coarse services, split on evidence	Proposed
0032	REST `api()`, generated client, prefixed UUIDv7 ids	Superseded by 0142
0033	Pub/Sub and cron with a transactional outbox	Superseded by 0078
0034	Object storage, GuardDuty malware scan, upload limits	Proposed
0035	Resend email with SPF, DKIM and DMARC	Proposed
0036	Idempotency in Encore cache for 24h; Postgres for money	Superseded by 0136
0037	API versioning by the `Stackra-Version` date header	Superseded by 0118
0038	Rate limits: app token buckets and Cloudflare WAF	Proposed
0039	OpenAPI to Mintlify API reference; OAuth developer guide	Proposed
0040	Services are organised as DDD feature modules	Superseded by 0130
0041	Decorated controllers, handlers and crons via a build-time generator	Superseded by 0091
0042	DI-first with one container per service	Accepted, amended by 0143, 0147
0043	`@stackra/workflow` is Medusa-style steps and workflows	Superseded by 0102
0044	Laravel-style package configuration	Superseded by 0146
0045	`@stackra/tenancy`: pool by default, silo on demand	Superseded by 0088
0046	Global data invariants and per-model opt-ins	Superseded by 0134
0047	Audit service fed by events	Proposed
0048	Point-in-time recovery and a quarterly restore drill	Proposed
0049	`@stackra/search`: a driver interface, Postgres first	Superseded by 0089
0050	`@stackra/ai` on AI SDK core, Bedrock by default	Superseded by 0100
0051	Better Auth identity service	Superseded by 0087
0052	The console is a Vite + React single-page app	Proposed
0053	Routes are decorator classes compiled to router adapters; no file-based routing	Proposed
0054	TanStack Query for server state, Zustand for client state	Superseded by 0079
0055	Forms use react-hook-form and Zod with thin HeroUI field adapters	Proposed
0056	HeroUI v3 and Pro on web; share logic and tokens, not components	Proposed
0057	The landing site is React Router 7 framework mode on Cloudflare Workers	Proposed
0058	The desktop app is Electron	Proposed
0059	Mobile offline: encrypted persisted Query cache and a persisted mutation queue	Proposed
0060	i18n keys and logical CSS from day one; English launch; light and dark	Superseded by 0080
0061	Mobile keeps React Navigation 7 and native tabs; one app	Proposed
0062	Mobile: EAS Update, Expo push and Sentry from day one	Proposed
0063	Cloudflare hosts the web surfaces	Proposed
0064	Unused: the number was never assigned	—
0065	The Linear gate is checked offline	Accepted
0066	Claude leads; OpenCode executes routed tasks in worktrees	Accepted
0067	spec-kit is the SDLC, with a mandatory clarify gate	Accepted
0068	runway: CI/CD built inside Stackra	Proposed
0069	Testing strategy and coverage floors	Proposed
0070	Quality budgets: accessibility, Web Vitals, bundle, mobile startup	Proposed
0071	Privacy: export, erasure, platform declarations and templates	Proposed
0072	SOC 2 groundwork	Proposed
0073	Observability: Better Stack, Sentry and Encore tracing	Proposed
0074	Open core: `@stackra-pro` on the private registry	Superseded by 0077
0075	Stackra ships packages; Figentra OS ships the product services	Proposed
0076	Every package runs in SaaS, on-prem and air-gapped deployments	Proposed
0077	Open core: the free and Pro package lists	Proposed
0078	The messaging layer: eight packages, one question each	Accepted, amended by 0141, 0148
0079	Client state is @stackra/state (ported Figentra signals); Query owns optimism and the offline queue	Proposed
0080	i18n is the ported Figentra i18n package; i18next is dropped	Proposed
0081	The gate chain is fully configurable per app, with a warning when tenancy or iam is omitted	Superseded by 0138
0082	Public ids are a prefix plus base32 of one UUIDv7; four API areas	Accepted, amended by 0135
0083	npm scopes: @stackra for packages, @figentra for this repository’s apps and services; @stackra/console is the CLI framework	Proposed
0084	Figentra OS package port plan	Proposed
0085	Logger reporters: CloudWatch kept; Encore log, Sentry and Better Stack added	Superseded by 0147
0086	@stackra/notifications is a full engine, with every channel free	Proposed
0087	Identity and IAM are driver packages; enterprise features plug in as Pro	Proposed
0088	@stackra/tenancy: pool and RLS are free; DB-per-tenant and the scope tree are Pro	Proposed
0089	@stackra/search is written fresh; Meilisearch and OpenSearch are Pro drivers	Proposed
0090	Codegen discovers decorators through each member’s root module	Accepted, amended by 0144
0091	The Encore app is generated into .stackra/encore; services hold no Encore files	Accepted, amended by 0158
0092	The IR is ported with decorator-derived kinds; the definition package is dropped	Accepted
0093	Better Auth integration: container hooks, iam-only authorization, an owned MikroORM adapter, global auth tables	Proposed
0094	Decorators are the only authoring style; workflows are declarative @Step graphs	Accepted, amended by 0145, 0152
0095	@stackra/validation: Laravel-style decorators compiled to one Zod schema, plus an output serializer	Accepted, amended by 0133
0096	Trait naming grammar and the trait list	Accepted, amended by 0133
0097	@stackra/model and @stackra/database; gen emits MikroORM EntitySchema	Accepted, amended by 0133
0098	Actions are the unit of behaviour, in @stackra/actions, with one pipeline and a typed actor	Accepted, amended by 0136, 0137, 0139, 0155
0099	One action risk scale, L0 to L4, with derived MCP hints and effect tags; change risk is R0 to R3	Accepted
0100	One free @stackra/ai: agents, tools, skills, MCP and A2A on AI SDK, every tool call an action	Accepted, amended by 0155, 0156
0101	Every operation is an action; a workflow sits behind it only when the criteria hit	Accepted
0102	The workflow engine: in-process steps with a Postgres journal, outbox staging and hooks, ported from Medusa’s MIT code	Accepted, amended by 0151, 0152
0103	@stackra/locking: server-side named locks behind a driver	Accepted, amended by 0149
0104	Cross-module relations are @Link declarations, read through query.graph	Accepted
0105	@Crud generates a model’s service methods and opt-in actions	Accepted
0106	Infisical Agent Vault, split by environment; the model never sees a secret	Accepted
0107	Three homes for keys; tenant credentials live in @stackra/connections	Accepted
0108	Scoped settings: each service owns its values; the registry owns the schema	Accepted
0109	The registry: build manifests published by CI to a Postgres-backed registry service	Accepted
0110	The experience service is server-driven UI at level L2: trees of registered coded components, no code over the wire	Accepted, amended by 0139, 0154
0111	The module is the unit of contribution; services and apps only host modules	Accepted
0112	Experience packages, @stackra/ui parity and the renderer kit	Accepted
0113	HeroUI Pro reaches Stackra Pro customers as a private mirror bundle, with a bring-your-own-key option	Accepted
0114	The page builder builds every page, including our own marketing site; MDX and Sanity are dropped	Accepted
0115	Built forms are documents of kind form; they submit to an action; the editors are Pro	Accepted
0116	@stackra/content: content types are models with a trait bundle; custom fields are a free, bounded trait	Accepted
0117	Shared primitives live in @stackra/contracts, each package has a types-only ./contracts entry, and each package owns its decorators	Accepted, amended by 0140, 0141, 0144
0118	@stackra/versioning is built now and stays dormant: date versions pinned per API key or OAuth app	Accepted, amended by 0136
0119	Merge policy: Quality Gate is the only required check; Claude merges only through pnpm pr:merge	Accepted
0120	The SDLC: specs in .agents/specs, four lanes, and change risk R0 to R3	Accepted
0121	SDLC tooling: sdlc retired, spec-kit pinned, a local Linear extension, the ported roles and who runs what	Accepted
0122	The workflow studio: coded workflows, configurable knobs, and tenant automations as data that references code	Accepted, amended by 0153, 0154
0123	Delivery order follows the dependency graph: package-disjoint waves, spikes first, assumed defaults pending the owner	Proposed
0124	Encore is the generated runtime target; service source stays plain TypeScript	Accepted, amended by 0158
0125	The constitution is amended to match Accepted ADRs and locked owner decisions	Accepted
0126	Member shapes and scaffold templates: service skeleton, entries-first packages, kind folders, four app kinds	Accepted
0127	Package categories, including infrastructure	Accepted
0128	Code conventions: enums, classes, components and kind folders	Accepted
0129	Code standards enforced by a house lint plugin, shipped as @stackra/coding-standard	Accepted
0130	Module layout by semantic kind; no controllers	Accepted
0131	Module key, version and deprecation	Accepted
0132	Permissions are a module catalogue; policies are providers	Accepted
0133	Field semantics, model keys, rename-safe fields and lifecycle events	Accepted
0134	Data invariants, field classification and the delete lifecycle	Accepted
0135	Public id format: prefix plus Crockford base32 of one UUIDv7	Accepted
0136	The action runtime contract: handler context, transaction, idempotency and versions	Accepted
0137	Declared action options and refusal reasons	Accepted
0138	The pipeline order is fixed; apps toggle and parameterise gates	Accepted
0139	Actions declare their user experience	Accepted
0140	The error envelope and error kinds	Accepted
0141	Integration event names and the envelope	Accepted
0142	Cross-service transport goes through drivers	Accepted
0143	Container scopes, module registration, lifecycle and testing	Accepted
0144	A typed MetadataRegistry, and every decorator package ships an Explorer	Accepted
0145	Tokens are defineToken values; container-backed global helpers are banned	Accepted
0146	Package configuration: TypeScript files, layered overrides and secret references	Accepted
0147	Logger and runtime telemetry defaults	Accepted
0148	Queue and scheduler: full job features, fair queuing and tenant schedules	Accepted
0149	Locking: fencing tokens, auto-renew and @WithLock	Accepted
0150	@stackra/cache: memory, Valkey, Encore and Postgres drivers with tenant-namespaced keys	Accepted
0151	The workflow engine is a port with a native driver and a Temporal driver	Accepted
0152	Workflow semantics: timeouts, waits, pinned versions, operations and one graph format	Accepted
0153	Automations run as principals; every package exposes its capabilities as building blocks	Accepted
0154	Tenant code runs only in a sandboxed code step	Accepted
0155	AI-native rule: queries are MCP tools, and all AI code is free	Accepted
0156	The AI runtime: provider drivers, a managed-runtime driver, memory and guardrails	Accepted
0157	stackra inspect and stackra diff	Accepted
0158	Gen artefacts: committed OpenAPI and manifest, a CI-published client, deploy-mode targets	Accepted
0257	Secret-manager agent and the secrets inbox: values written blind, nobody reads them	Proposed

Copy the template, give it the next number, and add it to this table and to docs.json. Cite Stackra ADRs by path, never by a number from another repository.