Advanced rule & orchestration engine for Frappe/ERPNext — dynamic rules, MDM, and process automation.
FlexiRule
[](https://github.com/Sendipad/flexirule/actions/workflows/ci.yml?query=branch%3Adevelop)
Visual Rule Engineer & Orchestration Engine for Frappe apps and ERPNext
The Visual Rule Builder is the canonical representation of FlexiRule logic — what you see is exactly what executes.
---
## 🚀 Overview
In modern enterprise systems like **Frappe / ERPNext**, business logic often evolves into a fragmented web of Python hooks scattered across multiple custom apps. This technical debt leads to "hook-hell," where execution order is implicit, debugging is a nightmare, and upgrades are risky.
**FlexiRule** changes the paradigm by providing a **visual, graph-based orchestration layer**. Instead of writing hidden code, you design executable business logic visually — with full control, observability, and safety.
### 💎 Why FlexiRule?
- **Centralized Logic**: Move rules out of scattered `.py` files into a single, auditable dashboard.
- **No-Code Configuration**: Custom UI controls (pickers, autocomplete) allow complex logic setup without a single line of code.
- **Explicit Execution**: Connections define deterministic paths. No more guessing which hook runs first.
- **Schema-Driven UI**: Configuration forms for custom logic are auto-generated from JSON schemas.
---
## 🖼️ Visual Tour
View Detailed Screenshots
Declarative, deeply nested condition trees with deterministic evaluation.
Process Operations — schema-driven configuration rendered dynamically at runtime.
---
## 🧠 The Mental Model
FlexiRule is built around three core pillars that bridge the gap between design and execution.
### 1. The Rule (The Entry Point)
A **Rule** defines _when_ logic should trigger. It serves as the gateway to the graph and binds to one of three context sources:
- **DocType Event**: Tied to database hooks (e.g., `Before Save`, `On Submit`).
- **Scheduler Event**: Scheduled CRON-based executions via background jobs.
- **Callable Event**: A sub-rule meant strictly to be executed by other parent rules via `Priority: 0`.
### 2. The Rule Action (The Node)
Each node in the graph is a **Rule Action**. It represents a specific step in your business process. Actions accept structured inputs and define the next step in the flow based on their outcome (e.g., `Success` → `Next Step`, `Error` → `Rollback`).
### 3. Process & Operations (The Logic)
A **Process** is a file-backed module (similar to Frappe Reports/Dashboards) that acts as a container for reusable logic.
- **File-Backed**: Logic is stored in code (`.py`) for performance and version control.
- **Operations**: Individual functions within a process that declare their own **JSON Schema** for configuration parameters.
---
## ⚡ Execution Flow Example
FlexiRule uses a deterministic graph-based execution engine with built-in cycle detection (preventing infinite loops over 100 iterations natively).
```mermaid
graph LR
Trigger[Rule Trigger]
--> Validate[Validate Data]
Validate -->|Valid| Dedup[Check Duplicates]
Validate -->|Invalid| Stop[Stop & Notify]
Dedup -->|Found| Block[Block Save]
Dedup -->|None| Enrich[Enrich Document]
Enrich --> Success[Finalize]
```
---
## 🛠️ Key Features
- **Vue 3 Visual Builder**: Smooth graph-editing via a VueFlow canvas rendered dynamically from Frappe backend schemas.
- **Condition Compilation**: The visual engine builds JSON `trigger_conditions` that are transparently pre-compiled into ultra-fast, single-pass pure Python strings `compiled_expression` on Save to avoid runtime overhead.
- **Deterministic Graph**: Zero ambiguity in execution order. Handlers resolve path branches dynamically using the Registry strategy pattern.
- **Role-Based Security**: Control which rules run for specific user roles.
- **Monitoring & Logs**: Full execution trace for every rule run, including input/output states and performance stats.
- **Safety First**: Sandboxed execution context via `SafeFrappeAPI`, exponential backoff retries, and centralized savepoint rollbacks.
- **Pure Terminology**: Evolved from _UPH → Bolton_ into a clean, standardized, and scalable architecture.
---
## 📦 Installation
```bash
# Get the app
bench get-app flexirule https://github.com/Sendipad/flexirule.git
# Install to your site
bench --site [your-site] install-app flexirule
# Build assets
bench build --app flexirule
```
---
## 🔧 Extensibility
Developers can extend FlexiRule by creating **Standard Processes**:
1. Create a `Process` document and check **Is Standard**.
2. Frappe will generate `.py` and `.js` controllers in your app.
3. Define your logic in Python and your config UI schema in JSON.
4. Your custom logic immediately appears as a selectable operation in the Visual Builder.
---
## 🤝 Contributing
How to Contribute
**Join the FlexiRule Community!**
FlexiRule is evolving fast. Whether you are a developer, designer, or documenter, your expertise helps shape the future of visual automation in the Frappe ecosystem.
### How You Can Help
- 🐛 **Bug Reports**: Open an issue for any glitches.
- 💡 **Feature Requests**: Suggest new Nodes or Process Operations.
- 📖 **Documentation**: Help us clarify concepts or add examples.
- 🔧 **Pull Requests**: We welcome fixes, optimizations, and new features.
Follow [Frappe Coding Standards](https://frappeframework.com/docs/v14/user/en/guidelines/coding-standards) and ensure all tests pass.
---
FlexiRule — Declarative, Visual, and Safe Business Logic for Frappe.
Built with ❤️ by the community.