Rulecatch

Rule Engine Overview

Audience: Customer — this page documents how the rule engine detects violations.

The Rulecatch Rule Engine runs as the Tasks service (packages/rule-checker), a background daemon that processes events in real-time using MongoDB Change Streams.

Architecture

ai_pooler_user_events (MongoDB)
         │
         │ Change Stream (insert events)
         ▼
┌─────────────────────────────┐
│       Tasks Service          │
│                              │
│  1. Receive new event        │
│  2. Update AI stats          │
│  3. Load user's rules        │
│  4. Match against event      │
│  5. Create violations        │
│  6. Check corrections        │
│  7. Process alerts           │
│  8. Mark event as checked    │
│                              │
└─────────────────────────────┘
         │
         ▼
user_rules_violations (MongoDB)

Key Properties

Property Value
Detection latency < 100ms (Change Streams, no polling)
Template cache 5-minute TTL
User config cache 1-minute TTL
Template count 200+ across 17 categories
Always-active rules AI Errors (bypass stack selection)
Custom rules Enterprise plan only
HTTP server None — purely a background process

Processing Pipeline

For each new event inserted into ai_pooler_user_events:

Step 1: Update AI Stats

Every event type (not just tool_call) updates pre-computed daily AI stats in user_daily_ai_stats. This powers the dashboard's overview and AI sessions pages.

Step 2: Filter Event Type

Only tool_call events proceed to rule checking. Other event types (session_start, session_end, turn_complete) are marked as ruleChecked: true and skipped.

Step 3: Resolve Rules

The engine builds a list of matchable rules for the user:

  1. Template rules — From the cached Global.ruleTemplates collection, filtered by the user's stack categories, excluding templates the user has disabled
  2. Always-active rules — Templates with alwaysActive: true (e.g., AI Errors) that apply regardless of stack
  3. Custom rules — From user_rules collection (Enterprise users)

Step 4: Match Conditions

Each rule's conditions are checked against the event using AND logic — all conditions must match for a violation. See Matching for details on operators and evaluation.

Step 5: Create Violations

For matching rules, a violation document is created with:

  • Rule reference (templateId or ruleId)
  • Severity, category, and rule name
  • Violation file path and line number (if detectable)
  • Git context (username, branch, repo)
  • corrected: false initially

Violations are bulk-inserted, then:

  • Daily violation stats are updated (user_daily_violation_stats)
  • Recent violations cache is updated (user_recent_violations)
  • Alert processing is triggered

Step 6: Check Corrections

If the event modifies a file that has uncorrected violations, the engine re-checks each violation's conditions against the new event. If the conditions no longer match, the violation is marked as corrected: true.

Step 7: Process Alerts

For each violation, the engine checks all of the user's enabled alerts:

  • Does the alert monitor this rule?
  • Does the severity match?
  • What frequency is configured (immediate, hourly, daily)?
  • Is the channel allowed for this plan?

Immediate alerts are sent right away. Hourly and daily alerts are queued in alert_digest_queue for batch processing.

Step 8: Mark Processed

The event's ruleChecked field is set to true to prevent reprocessing.

Caching Strategy

Template Cache (5-min TTL)

Templates are loaded from Global.ruleTemplates and organized by category in a Map<string, CachedTemplate[]>. Always-active templates are stored in a separate array.

The cache is refreshed:

  • On service startup
  • When the 5-minute TTL expires (checked before each event)

User Config Cache (1-min TTL)

Per-user configuration (stack selection, disabled templates, plan) is cached in a Map<string, CachedUserConfig>. The shorter TTL ensures changes propagate quickly when users modify their settings.

Dev-Safe Patterns

The rule engine strips certain development-safe patterns before matching to reduce false positives:

  • localhost URLs and references
  • 127.0.0.1 addresses
  • 0.0.0.0 addresses

This prevents rules about hardcoded URLs from triggering on local development references.

Connection Details

Setting Value
Max pool size 5
Min pool size 1
Idle timeout 30 seconds
Server selection timeout 5 seconds

The Tasks service connects to both the regional RuleCatch database and the Global database (for rule templates).

See Also

Rules & Templates →