Rules Engine & Webhooks
Relevant source files
The following files were used as context for generating this wiki page:
The Rules Engine & Webhooks system provides a visual and programmatic framework for managing automation and event-driven notifications within CodeBot. It allows administrators to define logic-based triggers (IF/THEN rules) to monitor system metrics, detect anomalies, and execute automated actions or forward events to external endpoints via webhooks. Sources: webapp/README.md, webapp/templates/settings.html:842-845
System Architecture
The Rules Engine is integrated into the core services layer, interacting with the storage layer for persistence and the webapp layer for administrative management. It evaluates incoming data against a set of predefined conditions and executes associated actions when matches are found.
The diagram shows the flow from the Administrative UI through the API into the core evaluation engine, which persists data in MongoDB and triggers actions. Sources: GUIDES/ARCHITECTURE.md:25-30, webapp/rules_api.py:16-18
Rule Engine Components
The engine is composed of several specialized modules that handle the lifecycle of a rule, from creation and validation to storage and testing.
API and Storage
The system utilizes a dedicated API blueprint for rule management, requiring administrative privileges for all operations. Persistence is handled by a storage service that manages MongoDB collections for rules. Sources: webapp/rules_api.py:16-52
| Component | Description |
|---|---|
rules_bp | Flask Blueprint for the Visual Rules API. |
get_rules_storage | Service for persisting and retrieving rules from MongoDB. |
EvaluationContext | Holds the data and metadata required for a single rule evaluation. |
AVAILABLE_FIELDS | A registry of valid fields that can be used in rule conditions. |
Sources: webapp/rules_api.py:16-25, webapp/rules_api.py:101-104
Rule Evaluation Logic
The evaluation process involves checking incoming data against conditions defined in the rule. The EvaluationContext provides the necessary environment, including support for verbose logging during testing to debug rule matches. Sources: webapp/rules_api.py:116-120
This sequence demonstrates the simulator/testing flow where an admin can verify rule logic before deployment. Sources: webapp/rules_api.py:101-140
Visual Rules API Endpoints
The API supports full CRUD operations and testing capabilities for rules. Access is strictly controlled via an admin_required decorator. Sources: webapp/rules_api.py:38-42
| Endpoint | Method | Description |
|---|---|---|
/api/rules | GET | Lists rules with optional filtering by enabled status or tags. |
/api/rules | POST | Creates a new rule with a generated UUID. |
/api/rules/fields | GET | Returns a list of all available fields for condition building. |
/api/rules/test | POST | Simulates a rule evaluation against provided test data. |
/api/rules/<id> | PUT | Updates an existing rule configuration. |
/api/rules/<id>/toggle | POST | Enables or disables a specific rule. |
Sources: webapp/rules_api.py:65-98, webapp/rules_api.py:143-205, webapp/README.md
Webhooks and External Integrations
Webhooks serve as the primary mechanism for the Rules Engine to communicate with external systems. When a rule match occurs, the engine can be configured to send a payload to a pre-defined HTTP endpoint.
GitHub Webhooks
The project specifically includes a Repo Sync Engine that utilizes GitHub webhooks for automated code synchronization. The endpoint POST /api/webhooks/github is used to receive repository events. Sources: webapp/templates/settings.html:805-816, webapp/README.md
External events from GitHub or internal metrics are processed by the engine to trigger notifications or further webhooks. Sources: webapp/templates/settings.html:805-816, GUIDES/ARCHITECTURE.md:54-66
Administrative Monitoring
Administrators can monitor the configuration and health of the rules system through specialized dashboards.
- Config Inspector: Allows review of environment variables, identifying missing or modified defaults related to API keys and integration settings. Sources: webapp/templates/admin_config_inspector.html:283-300
- Visual Rules Dashboard: A Drag & Drop interface for building IF/THEN rules and managing automated alerts. Sources: webapp/templates/settings.html:842-850
- Observability Dashboard: Provides real-time monitoring of alerts and performance metrics derived from rule executions. Sources: webapp/templates/settings.html:775-788
Conclusion
The Rules Engine & Webhooks module is a critical infrastructure component for CodeBot's automation. By combining a flexible visual rule builder with robust API endpoints and webhook support, the system enables sophisticated monitoring and responsive actions across the application's ecosystem. Sources: webapp/README.md, FEATURE_SUGGESTIONS/IMPROVEMENT_SUGGESTIONS.md:275-290