feat(docs): add comprehensive documentation for Flutter Policy Engine

Author: dgarciasquare1

docs.json

@@ -0,0 +1,51 @@
+{
+  "name": "Flutter Policy Engine",
+  "description": "A comprehensive policy management and access control system for Flutter applications",
+  "sidebar": [
+    {
+      "group": "Getting Started",
+      "pages": [
+        {
+          "title": "Introduction",
+          "href": "/",
+          "icon": "rocket"
+        },
+        {
+          "title": "Quick Start",
+          "href": "/quick-start",
+          "icon": "play"
+        },
+        {
+          "title": "Installation",
+          "href": "/installation",
+          "icon": "download"
+        }
+      ]
+    },
+    {
+      "group": "Core Concepts",
+      "pages": [
+        {
+          "title": "Policy Management",
+          "href": "/core-concepts/policy-management",
+          "icon": "shield"
+        }
+      ]
+    },
+    {
+      "group": "Examples",
+      "pages": [
+        {
+          "title": "Basic Policy Demo",
+          "href": "/examples/basic-policy-demo",
+          "icon": "code"
+        },
+        {
+          "title": "Role Management Demo",
+          "href": "/examples/role-management-demo",
+          "icon": "settings"
+        }
+      ]
+    }
+  ]
+}

docs/core-concepts/policy-management.mdx

@@ -0,0 +1,210 @@
+---
+title: Policy Management
+description: Understanding policy management in the Flutter Policy Engine
+---
+
+# Policy Management
+
+Policy management is the core concept of the Flutter Policy Engine. It involves defining, organizing, and enforcing access control policies that determine what content and features users can access based on their roles.
+
+## 🎯 What is Policy Management?
+
+Policy management is the systematic approach to:
+
+- **Defining Access Rules**: Establishing who can access what resources
+- **Organizing Permissions**: Structuring permissions in a logical hierarchy
+- **Enforcing Policies**: Applying access control rules consistently
+- **Managing Changes**: Updating policies as requirements evolve
+
+## 🏗️ Policy Architecture
+
+The Flutter Policy Engine uses a hierarchical policy architecture:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Policy Manager                           │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
+│  │   Role Storage  │  │ Policy Evaluator│  │ Role Manager │ │
+│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+         │                           │
+         ▼                           ▼
+┌─────────────────┐    ┌─────────────────────────────┐
+│   Role Model    │    │      Policy Widget          │
+│  - Name         │    │  - Role-based rendering     │
+│  - Permissions  │    │  - Access control           │
+└─────────────────┘    └─────────────────────────────┘
+```
+
+## 🔑 Core Components
+
+### 1. Policy Manager
+
+The `PolicyManager` is the central orchestrator that:
+
+- **Initializes Policies**: Sets up the initial role and permission structure
+- **Evaluates Access**: Determines if a role has access to specific content
+- **Manages Roles**: Handles role creation, updates, and removal
+- **Provides Context**: Makes policy information available to the widget tree
+
+```dart
+final policyManager = PolicyManager();
+
+// Initialize with role definitions
+await policyManager.initialize({
+  "admin": ["LoginPage", "Dashboard", "UserManagement", "Settings"],
+  "user": ["LoginPage", "Dashboard"],
+  "guest": ["LoginPage"]
+});
+```
+
+### 2. Role Model
+
+A `Role` represents a user category with specific permissions:
+
+```dart
+class Role {
+  final String name;
+  final List<String> allowedContent;
+
+  Role({required this.name, required this.allowedContent});
+}
+```
+
+**Key Properties**:
+
+- **name**: Unique identifier for the role
+- **allowedContent**: List of content types the role can access
+
+### 3. Policy Evaluator
+
+The policy evaluator determines access rights:
+
+```dart
+// Check if a role has access to specific content
+bool hasAccess = policyManager.evaluateAccess(role, content);
+```
+
+## 📋 Policy Definition
+
+### Basic Policy Structure
+
+Policies are defined as a map of roles to their allowed content:
+
+```dart
+final policies = {
+  "admin": ["LoginPage", "Dashboard", "UserManagement", "Settings"],
+  "user": ["LoginPage", "Dashboard"],
+  "guest": ["LoginPage"]
+};
+```
+
+### Content Types
+
+Content types represent different features or sections of your app:
+
+```dart
+// Common content types
+const contentTypes = [
+  "LoginPage",        // Authentication pages
+  "Dashboard",        // Main dashboard
+  "UserManagement",   // User administration
+  "Settings",         // Application settings
+  "Reports",          // Analytics and reports
+  "Billing",          // Payment and billing
+  "Support",          // Customer support
+];
+```
+
+### Role Hierarchy
+
+Consider implementing a role hierarchy for complex permission systems:
+
+```dart
+// Hierarchical role structure
+final roleHierarchy = {
+  "super_admin": ["admin", "user", "guest"],
+  "admin": ["user", "guest"],
+  "user": ["guest"],
+  "guest": []
+};
+
+// Inherited permissions
+class HierarchicalRole extends Role {
+  final List<String> inheritedRoles;
+
+  HierarchicalRole({
+    required String name,
+    required List<String> allowedContent,
+    required this.inheritedRoles,
+  }) : super(name: name, allowedContent: allowedContent);
+}
+```
+
+## 🔄 Policy Lifecycle
+
+### 1. Initialization
+
+```dart
+Future<void> initializePolicies() async {
+  final policyManager = PolicyManager();
+
+  // Define initial policies
+  final policies = {
+    "admin": ["LoginPage", "Dashboard", "UserManagement", "Settings"],
+    "user": ["LoginPage", "Dashboard"],
+    "guest": ["LoginPage"]
+  };
+
+  // Initialize the policy manager
+  await policyManager.initialize(policies);
+}
+```
+
+### 2. Policy Evaluation
+
+```dart
+// Evaluate access for a specific role and content
+bool canAccess = policyManager.hasAccess("user", "Dashboard");
+```
+
+### 3. Policy Updates
+
+```dart
+// Add a new role
+final newRole = Role(name: "moderator", allowedContent: ["LoginPage", "Dashboard"]);
+await policyManager.addRole(newRole);
+
+// Update existing role
+final updatedRole = Role(name: "user", allowedContent: ["LoginPage", "Dashboard", "Settings"]);
+await policyManager.updateRole(updatedRole);
+
+// Remove a role
+await policyManager.removeRole("guest");
+```
+
+## 🔄 Best Practices
+
+### 1. Policy Design
+
+- **Keep it Simple**: Start with basic roles and add complexity as needed
+- **Use Clear Names**: Use descriptive role and content names
+- **Document Policies**: Maintain clear documentation of policy structure
+- **Test Thoroughly**: Test all policy combinations
+
+### 2. Performance
+
+- **Cache Policies**: Cache frequently accessed policy data
+- **Optimize Queries**: Use efficient data structures for policy lookups
+- **Monitor Performance**: Track policy evaluation performance
+
+### 3. Security
+
+- **Validate Inputs**: Always validate policy data
+- **Encrypt Sensitive Data**: Encrypt policy data when appropriate
+- **Audit Access**: Log all policy-related operations
+- **Regular Reviews**: Regularly review and update policies
+
+## 📚 Next Steps
+
+- **[Basic Policy Demo](/examples/basic-policy-demo)**: Simple role-based access control demonstration