docs: add RBAC architecture decision records

[Prabhjot-Sethi]

Summary

• Add docs/architecture/rbac-decisions.md documenting the key architectural decisions for the fine-grained RBAC implementation
• Covers scope model design, constraint passing via headers, match criteria, performance architecture, and resource identifier extraction
• Focuses on reasoning and alternatives considered ("why" not "what") to help future developers understand the design

Test plan

• Review that decisions align with existing code behavior and planned FDP designs
• Verify no implementation details or API specs leaked into the architecture doc
• Confirm notes clearly distinguish current behavior from planned features

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added architectural decision documentation for role-based access control (RBAC) implementation, covering scope models, constraint management, performance strategies, and resource identifier handling.

[coderabbitai]

Walkthrough

A new architectural decision record document has been added to capture design rationale for fine-grained RBAC implementation, including scope models, constraint handling via headers, match criteria, performance architecture with in-memory snapshots, and resource identifier extraction strategies.

Changes

Cohort / File(s)	Summary
RBAC Architecture Documentation docs/architecture/rbac-decisions.md	New decision document outlining scope design (unscoped/tenant/org-unit), constraint header passing, match criteria patterns, zero-database-call performance architecture with snapshots and change streams, and resource identifier extraction strategy.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A blueprint for roles so fine-grained and true,
Headers and scopes, constraints that are new,
Snapshots in memory, no databases to call,
RBAC decisions documented for all! 📋✨

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fef4be9838

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Align documented scope tokens with gateway parser

This ADR lists scope config values as "tenant" and "org-unit", but the current request-path matcher only accepts a single scoped value of "ou" and rejects any other token with invalid scope (pkg/gateway/routes.go:118-121). If teams follow this table when registering routes, scoped endpoints will fail authorization at runtime, so the document should either use the currently supported token set or clearly label these values as a future schema change.

Useful? React with 👍 / 👎.