adr

Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for Bedrock.

ADRs document significant architectural decisions, the context in which they were made, and their consequences. They serve as a historical record of why things are the way they are.

Index

ADR	Title	Status	Date
001	TypeScript with Bun Runtime	Accepted	2025-12-06
002	Monorepo with Turborepo and FCIS + Ports Architecture	Accepted	2025-12-06
003	Testing Strategy	Accepted	2025-12-06
004	Documentation Site	Accepted	2025-12-12
005	Tested JSDoc Examples	Accepted	2025-12-13
006	ADR Enforcement	Accepted	2025-12-13
007	Open Cloud APIs Only	Accepted	2025-12-13
008	Zero Runtime Dependencies in @bedrock-rbx/ocale	Accepted	2026-04-12
009	Result Types Over Exceptions in @bedrock-rbx/ocale	Accepted	2026-04-12
010	SDK-Managed Rate Limiting and Retry in @bedrock-rbx/ocale	Accepted	2026-04-12
011	Simplified Architecture for Library Packages	Accepted	2026-04-12
012	Class-Based Clients with Per-Request Config Overrides	Accepted	2026-04-12
013	hk for Git Hook Management with AI-vs-Human Differentiated Gating	Accepted	2026-04-13
014	Vite+ as Unified Build, Test, and Task Toolchain	Accepted	2026-04-15
015	Mutation Testing with StrykerJS	Accepted	2026-04-16
016	Knip for Workspace-Level Unused Code Detection	Accepted	2026-04-17
017	Product Framing: Programmatic IaC with CLI Convenience (Level 2 Hybrid)	Accepted	2026-04-17
018	Architecture Refinement: FCIS + Ports with Explicit Primary/Driven Port Distinction	Accepted	2026-04-17
019	State Data Model and Diff Algebra (Mantle Parity)	Accepted	2026-04-17
020	Project Config Definition	Accepted	2026-04-22
021	Resource Update Capability for File-Backed Kinds	Accepted	2026-04-22
022	By-Domain Folder Layout for @bedrock-rbx/ocale	Accepted	2026-04-30
023	Apply Semantics — Parallel, Continue-on-Failure, Per-Op Progress Events	Accepted	2026-05-14
024	Resource Redaction for Pre-Release Environments	Accepted	2026-05-14
025	Luau type definitions for bedrock.config.luau	Accepted	2026-05-19
026	Codegen and Two-Phase Deploy	Accepted	2026-06-22
027	Changesets for Versioning and Automated npm Publishing	Accepted	2026-06-22

Creating a New ADR

1. Use the adr agent to walk through the decision properly
2. Number sequentially (e.g., 001-feature-name.md)
3. Fill in all sections
4. Add it to the index above
5. Submit a PR for review

Statuses

• Proposed: Under discussion
• Accepted: Decision made and in effect
• Deprecated: No longer applies
• Superseded: Replaced by a newer ADR