feat: Rework modeling best practices document

[aaguiarz]

Description

https://openfga.dev/pr-preview/pr-1173/docs/best-practices/modeling-design-principles

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

Documentation

• Introduced comprehensive Authorization Model Design Principles guide covering domain-aligned modeling approaches, role design strategies (built-in and custom), organizational hierarchies, and resource type modeling. Includes practical examples, best practices guidance, and a quick-reference table for common authorization scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Documentation update replacing the previous "Modeling Best Practices" page with a new comprehensive "Authorization Model Design Principles" guide. The new documentation provides detailed modeling guidance, design patterns, and concrete OpenFGA DSL examples, while the old page is removed and the sidebar reference is updated accordingly.

Changes

Cohort / File(s)	Summary
Documentation Content docs/content/best-practices/modeling-design-principles.mdx	New comprehensive MDX documentation covering authorization model design principles, including domain-aligned modeling, role modeling strategies, organizational structures, resource type patterns, and a quick-reference recommendation table
Documentation Cleanup docs/content/best-practices/modeling.mdx	Removed entire documentation file containing previous modeling best practices guidance
Navigation Configuration docs/sidebars.js	Updated Best Practices sidebar entry: changed label from "Modeling Best Practices" to "Authorization Model Design Principles" and updated corresponding document id reference

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Add guidance for modeling roles #1048: Adds a dedicated "Modeling roles" documentation page that overlaps with the "Modeling roles" section included in this PR's new design principles guide.

Suggested reviewers

• dyeam0
• rhamzeh

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Rework modeling best practices document' accurately reflects the main change: refactoring the modeling best practices documentation by replacing the old modeling.mdx with a new modeling-design-principles.mdx file and updating the sidebar reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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.}

[github-actions]

PR Preview Action v1.8.0
🚀 View preview at https://openfga.github.io/openfga.dev/pr-preview/pr-1173/
Built to branch gh-pages at 2026-01-24 20:35 UTC. Preview will be ready when the GitHub Pages deployment is complete.