Modules Overview

TrustLens detection is organized as eight independent modules. Each module watches a specific class of behavior — refunds, orders, coupons, categories, linked accounts, shipping anomalies, chargebacks, and card-testing attacks — and contributes signals to the trust score. Modules run in parallel, can be toggled individually, and each emits signals you can audit on the customer profile. This guide is the orientation document; the detail docs for each module follow.

---

The Eight Modules #

Module	Module ID	What It Watches	Default
Return Abuse	returns	Refund rate, refund frequency, refund value, full vs partial ratio	Enabled
Order Pattern Analysis	orders	Completion rate, cancellation patterns, order velocity	Enabled
Coupon Abuse	coupons	First-order coupon repeats, coupon-then-refund cycles, stacking	Enabled
Category-Aware Risk	categories	Per-category return rate concentration	Enabled
Linked Accounts	linked_accounts	Shared address, phone, IP, payment method, or device fingerprint	Enabled
Shipping Anomalies	shipping_anomalies	Address hopping, country mismatches, address-change velocity	Enabled
Chargeback Tracking	chargebacks	Disputes, dispute outcomes, blended store-wide ratio	Enabled
Card-Testing Defense	card_testing	Decline velocity at checkout, attacker device fingerprints	Enabled

All eight ship in Free. Card-Testing Defense and Chargeback Tracking have Pro enhancements (auto-escalation, Chargeback Monitor page, etc.) but the core detection in both is available without Pro.

---

How Modules Work #

Every module follows the same interface, defined by the abstract TrustLens_Module class:

• register_hooks() — wires the module into WooCommerce events (order completed, refund issued, coupon applied, etc.) so it can record observations to the customer record
• get_signal($email_hash) — returns the module’s current signal contribution for a given customer: a score delta and a human-readable reason
• get_settings_fields() — declares the settings UI the module exposes
• is_enabled() — checks the per-module enable toggle

The scoring engine calls get_signal() on every enabled module during each recalculation. The module reads from the customer’s persistent record (counts, rates, stats) — not from the WooCommerce database directly — which is why scoring is fast even on stores with millions of orders.

---

Two Phases: Observe and Score #

Modules operate in two phases, separated in time.

Observe (event-driven) #

When a relevant WooCommerce event fires — a refund is created, a coupon is applied, a dispute webhook arrives — the module’s hook callback runs synchronously. The callback:

1. Reads what just happened
2. Updates aggregate counts on the customer’s row (e.g. total_refunds, first_order_coupons, total_disputes)
3. Logs an event to {prefix}trustlens_events for the timeline
4. Queues an asynchronous score recalculation

This phase is fast — single-row updates and one queue insert. No scoring happens here.

Score (async) #

When the queued recalculation runs (typically within 1–2 minutes), the scoring engine calls get_signal() on every enabled module. Each get_signal() reads the customer’s aggregate stats, applies the module’s rules, and returns its current contribution. The engine sums signals, applies the bonus, clamps, and writes the new score.

This separation means a busy event (e.g. ten refunds in a minute) updates the persistent record ten times but only triggers one or two score recalculations. The deduplication is in the queue, not in the observation logic.

---

Module Independence #

Modules do not communicate with each other directly. The Coupons module doesn’t know about chargebacks; the Linked Accounts module doesn’t know about returns. The only shared surface is:

• The customer’s persistent record (stat columns each module owns)
• The score recalculation queue
• A handful of cross-module hooks (e.g. trustlens/linked_accounts_detected, which the Coupons module subscribes to for the “first-order coupons across linked accounts” pattern)

This makes modules easy to reason about in isolation. It also means you can disable any module without breaking the others — the score simply won’t include that module’s contribution anymore.

---

Enabling and Disabling Modules #

From TrustLens → Settings → Modules, every module has an on/off toggle. The behavior when disabled:

• Hooks are not registered — the module won’t observe new events
• get_signal() is not called — no contribution to scores
• Existing aggregate stats on customer records are preserved — re-enabling resumes scoring without rebuilding
• Settings UI for that module is hidden from the modules tab

Disabling a module is reversible. Toggling a module back on doesn’t recalculate existing scores automatically — use bulk recalculate from the customers list, or wait for the next event-triggered recalc.

---

Per-Module Settings #

Each module exposes its own settings sub-section under Settings → Modules. Common settings:

Setting Type	Examples
Sensitivity thresholds	Return rate tiers (25 / 40 / 60%), coupon abuse counts, chargeback weights
Velocity windows	Address change window (7–90 days), decline velocity windows
Lookback windows	How far back to consider for category-aware risk
Action toggles	“Block linked-account coupon abuse,” “Auto-block after N lost disputes”
Category weights	Per-category multipliers for Category-Aware Risk

Defaults are tuned for typical e-commerce. Leave them alone for the first two weeks, then adjust based on observed false positives or missed signals.

---

Module Status on the Dashboard #

The Module Status Pills row on the Dashboard shows each module’s state at a glance:

• On/Off indicator — green dot if enabled, gray if disabled
• One headline stat — e.g. “12 customers flagged this week” (Returns), “3 fraud rings detected” (Linked Accounts), “0 active attacks” (Card Testing)
• Click target — clicking jumps to the module’s settings or detail view

This is the fastest way to verify every module is alive and producing signals.

---

Free vs Pro at the Module Level #

All eight module detection engines are in Free. Pro adds extensions, not replacements:

Module	Free Detection	Pro Adds
Returns	Complete	—
Orders	Complete	—
Coupons	Complete	—
Categories	Complete	—
Linked Accounts	Complete	—
Shipping Anomalies	Complete	Diversity-trend detection, enhanced country-mismatch severity
Chargebacks	Stripe/WooPayments ingestion, manual entry, blended ratio	Dedicated Chargeback Monitor page, per-brand breakdown, Dispute Evidence Report, ratio email alerts, auto-block after N lost
Card-Testing	Velocity detection, fingerprint lockouts, Panic Freeze, VIP bypass	Auto-escalation, geo-diversity safeguard, IP/fingerprint allowlists, 12-font fingerprint, Attack History, Slack alerts

---

Adding Custom Modules #

The module system is extensible. To add a custom detection module:

1. Create a class extending TrustLens_Module
2. Implement register_hooks() and get_signal()
3. Register it via the trustlens/register_modules action

The custom module’s signals appear in customer signal breakdowns alongside built-in ones, contribute to scores normally, and respect the per-module enable toggle. See Extending with Custom Modules for a full example.

---

Module Performance Profile #

Detection has been engineered for production WooCommerce stores. Some performance characteristics worth knowing:

• Observation overhead per event: typically < 5ms — one indexed UPDATE plus one INSERT into the events table
• Scoring time per customer: typically < 50ms — eight module signal computations, each reading the customer’s aggregate stats from a single row
• Background work: all scoring happens through Action Scheduler with deduplication so duplicate triggers collapse
• Cache locality: the customer row is the unit of work — modules don’t fan out to other tables during scoring

The expensive operations (Historical Sync, ratio computations across all customers, fraud-ring graph walks) all run in batches outside the request path.

---

What’s Next #

The following pages dive into each module individually — what it observes, what signals it emits, what settings it exposes, and what false positives to watch for. Start with whichever module is most relevant to your store; they’re independent and can be read in any order.