docs(adr): add Architecture Decision Records 0001–0008 (#113)

[nanotaboada]

Summary

• Creates adr/ directory with template.md (Michael Nygard format) and README.md index
• Adds 8 ADRs (0001–0008): Rocket framework selection, four-layer architecture, Diesel/r2d2/bundled SQLite, UUID + squad number key strategy, full-replace PUT semantics, embedded migrations, integration-only test strategy, and Docker/Compose strategy
• Updates CLAUDE.md: resolves forward reference to adr/, adds linked ADR index, updates pre-commit checklist, moves "Claude Code" section to end of document
• Updates CHANGELOG.md [Unreleased] → Added with ADR entry

Test plan

• All 8 ADR files exist under adr/ and follow the Michael Nygard template (Status, Context, Decision, Consequences)
• Each ADR lists at least two alternatives and explains the trade-offs
• adr/README.md index links correctly to all 8 ADRs
• CLAUDE.md ADR section links resolve to the correct files
• cargo test passes with no regressions

Closes #113

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added 8 Architecture Decision Records documenting framework selection, system architecture, persistence strategy, resource identifiers, API semantics, database migrations, testing approach, and containerization.
  • Added guidelines and template for maintaining architectural decisions.

[coderabbitai]

Warning

Review limit reached

@nanotaboada, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 51 minutes and 59 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f785896e-f244-4fd7-979d-084ea35b84a6

📥 Commits

Reviewing files that changed from the base of the PR and between 142a471 and 938829d.

📒 Files selected for processing (12)

• CHANGELOG.md
• CLAUDE.md
• adr/0001-adopt-rocket-as-rest-api-framework.md
• adr/0002-four-layer-architecture.md
• adr/0003-diesel-r2d2-bundled-sqlite.md
• adr/0004-uuid-surrogate-squad-number-natural-key.md
• adr/0005-full-replace-put-no-patch.md
• adr/0006-embed-migrations-startup-schema.md
• adr/0007-integration-only-test-strategy.md
• adr/0008-docker-compose-strategy.md
• adr/README.md
• adr/template.md

Walkthrough

This PR implements a complete Architecture Decision Records (ADR) system for the project. It adds eight foundational ADRs documenting the choice of Rocket as REST API framework, a four-layer architecture pattern, Diesel/r2d2/bundled SQLite persistence stack, UUID/squad_number identifier strategy, full-replace PUT semantics, embedded migrations, integration-only testing, and Docker Compose deployment. The ADR directory includes infrastructure (README, template), and project governance is updated to require ADR creation for future architectural changes.

Changes

Architecture Decision Records Implementation

Layer / File(s)	Summary
ADR Framework & Project Integration adr/README.md, adr/template.md, CLAUDE.md	ADR directory README establishes immutability rules and indexes accepted ADRs (0001–0008); template provides standard structure (context, decision, consequences); CLAUDE.md now requires ADR creation/amendment for architectural changes and lists current ADRs.
Technology & Deployment Foundations adr/0001-adopt-rocket-as-rest-api-framework.md, adr/0003-diesel-r2d2-bundled-sqlite.md, adr/0008-docker-compose-strategy.md	Rocket 0.5.1 chosen for async Tokio-based REST API with attribute routing; Diesel 2.x with r2d2 pool and bundled libsqlite3 selected for compile-time query verification and zero system dependency; multi-stage Dockerfile with named SQLite volume for deployment.
Architecture Design & Data Model adr/0002-four-layer-architecture.md, adr/0004-uuid-surrogate-squad-number-natural-key.md, adr/0005-full-replace-put-no-patch.md	Strict four-layer architecture (Routes→Services→Repositories→State) separates HTTP, business logic, Diesel queries, and connection pool initialization; dual-key strategy uses UUID for internal GET /players/{uuid} and immutable squad_number for mutation routes; PUT only (no PATCH) simplifies update semantics by requiring full-record replacement.
Development Practices & Standards adr/0006-embed-migrations-startup-schema.md, adr/0007-integration-only-test-strategy.md	Diesel embed_migrations!() runs at startup before Rocket pool initialization, baking migrations into binary; integration-only tests against in-memory SQLite with max_size(1) and Rocket local::Client provide real schema/constraint enforcement without mocks or unit tests.
Release Documentation CHANGELOG.md	[Unreleased] → Added entry documents the new adr/ directory containing eight ADRs addressing framework, architecture, persistence, identifier strategy, HTTP semantics, migrations, testing, and deployment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Create adr/ directory with README.md, template.md, and ADRs 0001–0008	✅
Each ADR documents at least two alternatives and explains trade-offs	✅	All eight ADRs enumerate alternatives (context section) and list positive/negative/neutral consequences.
Update CLAUDE.md to reference adr/ and require ADR updates for architectural decisions	✅	Checklist now requires ADR creation/amendment; "Current ADRs" section lists 0001–0008.
Update CHANGELOG.md [Unreleased] section under "Added"	✅	New entry documents the eight ADRs and their key themes.

Possibly related issues

• [FEATURE] Migrate Player id from INTEGER to UUID ts-node-samples-express-restful#23 — Describes the same domain migration: UUID surrogate primary key with squad_number natural key for mutations (PUT /players/squadnumber/{n}, DELETE /players/squadnumber/{n}), and GET /players/{uuid} for admin read.

Possibly related PRs

• nanotaboada/rust-samples-rocket-restful#114 — Complements this PR by adjusting .coderabbit.yaml and additional CLAUDE.md tuning to enforce ADR review and align with documented Rocket/Diesel/r2d2 architectural rules.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits format (docs:), is descriptive (identifies ADRs 0001–0008 as the main content), includes the issue reference (#113), and is 61 characters (well under 80 limit).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #113

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/implement-architecture-decision-records-113

• 🛠️ sync documentation
• 🛠️ enforce http error handling
• 🛠️ idiomatic review
• 🛠️ verify api contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@adr/0002-four-layer-architecture.md`:
- Around line 31-33: The fenced code block containing "Routes → Services →
Repositories → State" is missing a language tag (triggering markdownlint MD040);
update the triple-backtick fence to include a language tag (e.g., change ``` to
```text) so the block becomes ```text ... ``` and markdownlint will accept
it—locate the block that contains the exact string "Routes → Services →
Repositories → State" and add the language tag to the opening fence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1a3d8a02-fcac-485f-98cb-003caf31c26e

📥 Commits

Reviewing files that changed from the base of the PR and between 7159a9e and 142a471.

📒 Files selected for processing (12)

• CHANGELOG.md
• CLAUDE.md
• adr/0001-adopt-rocket-as-rest-api-framework.md
• adr/0002-four-layer-architecture.md
• adr/0003-diesel-r2d2-bundled-sqlite.md
• adr/0004-uuid-surrogate-squad-number-natural-key.md
• adr/0005-full-replace-put-no-patch.md
• adr/0006-embed-migrations-startup-schema.md
• adr/0007-integration-only-test-strategy.md
• adr/0008-docker-compose-strategy.md
• adr/README.md
• adr/template.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.88%. Comparing base (42a1717) to head (938829d).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #118   +/-   ##
=======================================
  Coverage   84.88%   84.88%           
=======================================
  Files           6        6           
  Lines         172      172           
=======================================
  Hits          146      146           
  Misses         26       26           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.