Glossary

Auto-assign — The boolean flag on each rule that controls whether the rule fires at runtime. true (default) = active, false = stored but inactive.

ApplyStateUsergroups — The Go service method (users.Service.ApplyStateUsergroups(ctx, userID, stateCode)) that runs the rule lookup and upserts the matching groups onto the user. Called after CreateAddress and UpdateAddress.

CIDR — Notation for IP ranges (e.g. 203.0.113.0/24). NOT used by this module; included for contrast with access-restrictions.

Price tier — A quantity or usergroup-scoped price on a product. Usergroup-scoped tiers are a common downstream consumer of state-usergroup rules.

Rule — A single row in state_usergroup_rules mapping one state to one usergroup. Multiple rules per state are allowed.

state_code — The state / region code on the rule (e.g. CA, NY, TX). Matched exactly against the state saved on the customer's address.

state_name — Display label for the rule. Filled from the selected state in the admin form; not validated.

status='A' — Standard "active" flag on the usergroup_links row. The auto-assign upsert always writes A.

Tier resolution — The downstream process of picking which price applies to a customer with multiple usergroups. Out of scope for this module; lives in the cart price calculation.

Usergroup — The generic platform primitive for grouping customers. A user can be in N groups simultaneously. Privileges, price tiers, content visibility lists, etc. read from this primitive.

usergroup_links — Join table between users and usergroups. Carries (user_id, usergroup_id, status). State-usergroup rules INSERT here on auto-assign.

Address-write site — Any backend path that creates or updates a customer address row. Each one must call ApplyStateUsergroups after the write commits, or the auto-assign silently skips.

Module gate — The IsEnabled(tenant, "state-usergroup-rules") check inside ApplyStateUsergroups. Returns early if false; ensures the module switch in /admin/modules is enforced at runtime regardless of which call site invokes the service.

Back-fill — Retroactively running the rule against existing customers. Not built into the module. Implemented as a one-off SQL or a script that re-saves every address.

Fail-closed — A failure-mode pattern where errors during evaluation block the action. The module check is fail-closed: a lookup error skips the assignment without affecting the parent address write.