Envoy Business Unit Policy API

Architecture notes

Three patterns do most of the work in this system: the registry, the logic tree, and the query builder. They compose into a configuration layer that lets business users describe what they want without engineers translating it into code.

Registry-driven performance metrics

Each business metric — total premium, count of policies, agent commission — is declared once in a Python registry that says where the data lives, what to join, what to aggregate, and what filters are valid:

{
  "parameter": "issued_policy_premium_amount",
  "base_table": "crmp_issued_policies",
  "field": ["premium_amount"],
  "agg": "sum",
  "joins": [
    { "table": "crmp_policy_base",
      "on": "crmp_issued_policies.policy_base_id = crmp_policy_base.id" },
    { "table": "core_users",
      "on": "crmp_issued_policies.sales_agent_id = core_users.id" },
  ],
  "agent_field": "crmp_issued_policies.sales_agent_id",
  "filters": ["risk_type_id", "product_id", "policy_effective_date",
              "role_id", "agent_id"],
}

Adding a new metric is one registry entry — no controller changes, no serializer changes, no migration. The aggregation layer reads the registry at evaluation time and builds the SQL.

Recursive logic tree evaluation

Business rules are JSON trees. The evaluation engine recurses through them, short-circuiting on AND, finding a winner on OR, and bottoming out on leaf conditions that compare aggregated metrics to thresholds:

def evaluate_logic_tree(tree, performance_data, default_reward=None):
    if "logic" in tree:
        results = [
            evaluate_logic_tree(c, performance_data, default_reward)
            for c in tree["conditions"]
        ]
        if tree["logic"] == "AND":
            if all(r[0] for r in results):
                rewards = [r[2] for r in results if r[2] is not None]
                return True, [r[1] for r in results if r[1]], (max(rewards) if rewards else default_reward)
            return False, None, 0
        if tree["logic"] == "OR":
            for matched, cond, reward in results:
                if matched:
                    return True, cond, reward
            return False, None, 0
    # leaf condition
    return evaluate_leaf(tree, performance_data, default_reward)

This shape supports arbitrarily nested rules — "premium ≥ X AND (policies ≥ Y OR commission ≥ Z)" — without any new evaluator code per rule.

Dynamic query builder

The aggregation layer pulls every field referenced in a rule tree, looks each one up in the registry, and constructs the SQL on the fly through a fluent service (mServices) — selects, joins, agent filter, period filter, aggregation. One round trip per metric, indexed columns, no hand-rolled queries.

Why this composition

Once the three patterns exist, the system has a property most internal business platforms lack: business rule changes don't enter the engineering backlog. New metric → registry entry. New rule → JSON tree edit. New period type → one function. The engineering team owns the framework; the business owns the rules that run on it.