Skip to content

Commit f418f0e

Browse files
dgarciasquare1dgarciasquare1
committed
feat(docs)!: enhance README with detailed features and usage examples for Flutter Policy Engine
1 parent 4d61a40 commit f418f0e

File tree

1 file changed

+186
-32
lines changed

1 file changed

+186
-32
lines changed

‎README.md‎

Lines changed: 186 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,158 @@
1-
# flutter_policy_engine
1+
# Flutter Policy Engine
22

3-
A lightweight, extensible policy engine for Flutter. Define, manage, and evaluate access control rules declaratively using ABAC (Attribute-Based Access Control) or RBAC (Role-Based Access Control) models.
3+
[![Pub Version](https://img.shields.io/pub/v/flutter_policy_engine)](https://pub.dev/packages/flutter_policy_engine)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![Flutter](https://img.shields.io/badge/Flutter-3.4.1+-blue.svg)](https://flutter.dev)
46

5-
## Features
7+
A lightweight, extensible policy engine for Flutter applications. Define, manage, and evaluate access control rules declaratively using **ABAC** (Attribute-Based Access Control) or **RBAC** (Role-Based Access Control) models with a clean, intuitive API.
68

7-
- Attribute-Based and Role-Based Access Control (ABAC/RBAC)
8-
- Declarative rule definitions
9-
- Extensible and modular design
10-
- Easy integration with Flutter apps
9+
## ✨ Features
1110

12-
## Installation
11+
- **🔐 Dual Access Control Models**: Support for both Role-Based (RBAC) and Attribute-Based (ABAC) access control
12+
- **🎯 Declarative Policy Definitions**: Define access rules using simple, readable configurations
13+
- **🏗️ Modular Architecture**: Extensible design with clear separation of concerns
14+
- **⚡ Lightweight & Fast**: Minimal overhead with efficient policy evaluation
15+
- **🔄 Real-time Updates**: Dynamic policy updates without app restarts
16+
- **🎨 Flutter-Native**: Built specifically for Flutter with widget integration
17+
- **📱 Easy Integration**: Simple setup with minimal boilerplate code
18+
- **🧪 Comprehensive Testing**: Full test coverage with examples
1319

14-
Ensure you have [Flutter](https://docs.flutter.dev/get-started/install) and [Dart](https://dart.dev/get-dart) installed. [FVM](https://fvm.app/) is recommended for managing Flutter versions.
20+
## 🚀 Quick Start
21+
22+
### Installation
23+
24+
Add the package to your `pubspec.yaml`:
25+
26+
```yaml
27+
dependencies:
28+
flutter_policy_engine: ^1.0.1
29+
```
30+
31+
Run the installation:
1532
1633
```bash
17-
# Clone the repository and enter the directory
18-
git clone <repo-url>
19-
cd flutter_policy_engine
34+
flutter pub get
35+
```
2036

21-
# Run the setup script (requires bash, Flutter, Node.js, and npm)
22-
./setup.sh
37+
### Basic Usage
38+
39+
```dart
40+
import 'package:flutter/material.dart';
41+
import 'package:flutter_policy_engine/flutter_policy_engine.dart';
42+
43+
void main() async {
44+
WidgetsFlutterBinding.ensureInitialized();
45+
46+
// Initialize policy manager
47+
final policyManager = PolicyManager();
48+
await policyManager.initialize({
49+
"admin": ["dashboard", "users", "settings", "reports"],
50+
"manager": ["dashboard", "users", "reports"],
51+
"user": ["dashboard"],
52+
"guest": ["login"]
53+
});
54+
55+
runApp(MyApp(policyManager: policyManager));
56+
}
57+
58+
class MyApp extends StatelessWidget {
59+
final PolicyManager policyManager;
60+
61+
const MyApp({super.key, required this.policyManager});
62+
63+
@override
64+
Widget build(BuildContext context) {
65+
return PolicyProvider(
66+
policyManager: policyManager,
67+
child: MaterialApp(
68+
title: 'Policy Engine Demo',
69+
home: HomePage(),
70+
),
71+
);
72+
}
73+
}
74+
75+
class HomePage extends StatelessWidget {
76+
@override
77+
Widget build(BuildContext context) {
78+
return Scaffold(
79+
appBar: AppBar(title: Text('Dashboard')),
80+
body: Column(
81+
children: [
82+
// Only show for admin and manager roles
83+
PolicyWidget(
84+
role: "admin",
85+
content: "users",
86+
child: UserManagementCard(),
87+
fallback: AccessDeniedWidget(),
88+
),
89+
90+
// Show for all authenticated users
91+
PolicyWidget(
92+
role: "user",
93+
content: "dashboard",
94+
child: DashboardCard(),
95+
),
96+
],
97+
),
98+
);
99+
}
100+
}
23101
```
24102

25-
The setup script will:
103+
## 📚 Core Concepts
104+
105+
### Policy Manager
106+
107+
The central orchestrator that manages all access control logic:
108+
109+
```dart
110+
final policyManager = PolicyManager();
111+
112+
// Initialize with role definitions
113+
await policyManager.initialize({
114+
"admin": ["dashboard", "users", "settings"],
115+
"user": ["dashboard"],
116+
});
117+
118+
// Check access programmatically
119+
bool hasAccess = policyManager.evaluateAccess("admin", "users"); // true
120+
bool canAccess = policyManager.evaluateAccess("user", "settings"); // false
121+
```
122+
123+
### Policy Widget
124+
125+
Conditionally render content based on user roles:
126+
127+
```dart
128+
PolicyWidget(
129+
role: "admin",
130+
content: "settings",
131+
child: SettingsPage(),
132+
fallback: AccessDeniedWidget(),
133+
)
134+
```
135+
136+
### Role Management
137+
138+
Create and manage roles dynamically:
139+
140+
```dart
141+
// Add a new role
142+
await policyManager.addRole("moderator", ["dashboard", "comments"]);
26143
27-
- Check for Flutter and FVM
28-
- Install the Flutter version from `.fvm/fvm_config.json` (if present)
29-
- Install Dart/Flutter dependencies (`pub get`)
30-
- Install Node.js dependencies (if `package.json` exists)
31-
- Initialize Husky for git hooks (if present)
32-
- Add `.fvm/` to `.gitignore` if needed
144+
// Update existing role
145+
await policyManager.updateRole("user", ["dashboard", "profile"]);
33146
34-
## Testing
147+
// Remove a role
148+
await policyManager.removeRole("guest");
149+
```
150+
151+
## 🧪 Testing
35152

36153
### Local Testing
37154

38-
Run tests with coverage locally:
155+
Run tests with coverage:
39156

40157
```bash
41158
# Using the provided script (recommended)
@@ -48,20 +165,57 @@ genhtml coverage/lcov.info -o coverage/html
48165
open coverage/html/index.html
49166
```
50167

51-
## Contributing
168+
### Example App
169+
170+
Explore the interactive example app:
171+
172+
```bash
173+
cd example
174+
flutter run
175+
```
176+
177+
The example includes:
178+
179+
- Basic policy demonstrations
180+
- Role management interface
181+
- Real-time policy updates
182+
- Access control scenarios
183+
184+
## 📚 Documentation
185+
186+
- **[Quick Start Guide](docs/quick-start.mdx)** - Get up and running in minutes
187+
- **[Core Concepts](docs/core-concepts/)** - Deep dive into policy management
188+
- **[Examples](docs/examples/)** - Practical usage examples
189+
190+
## 🤝 Contributing
191+
192+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
193+
194+
### Development Setup
195+
196+
```bash
197+
# Clone the repository
198+
git clone https://github.com/aspicas/flutter_policy_engine.git
199+
cd flutter_policy_engine
200+
201+
# Run the setup script
202+
./setup.sh
203+
204+
# Run tests
205+
./scripts/test_with_coverage.sh
206+
```
52207

53-
Contributions are welcome! Please:
208+
### Code Style
54209

55-
- Follow the existing code style and patterns
56-
- Write clear commit messages (Commitlint and Husky are enabled)
57-
- Add or update tests for new features or bug fixes
58-
- Ensure all tests pass before submitting a pull request
59-
- Open a pull request with a clear description
210+
- Follow the existing code patterns and style
211+
- Write clear commit messages (Commitlint enabled)
212+
- Add tests for new features
213+
- Ensure all tests pass before submitting PRs
60214

61-
## License
215+
## 📄 License
62216

63217
MIT © 2025 David Alejandro Garcia Ruiz
64218

65219
---
66220

67-
> **Tip:** If you use VSCode, restart your terminal after setup to ensure FVM is properly detected.
221+
> **💡 Tip**: If you use VSCode, restart your terminal after setup to ensure FVM is properly detected.

0 commit comments

Comments
 (0)