Filtering System
 

Smart Engine for Customer Segmentation & New Leads

 

1. Conceptual Overview
 

The Filtering System is a dynamic data segmentation engine built to help users precisely control which customers or new leads appear in the system's list.
 

This is not just a UI filter.

It is a persistent, reusable, and export-aware filtering framework that drives:
 

• Customer & New Lead Lists

• Saved Views and Shortcuts

• Tabs and Orders Filtering

• Multi-Criteria Scoring Filters

• Export and Reporting Logic
   

Every filter applied becomes part of a unified query pipeline that the system understands and reuses across modules.
 

2. Where the Filtering System is Located
 

The Filtering System appears on the Customers / New Leads list page, visually integrated into the main customer table's toolbar.
 

• The entry point is a "Filters" hamburger-style button

• Clicking it opens a full filter popup window

• The popup is positioned above the list without navigating to another page

• Filters always apply to the current active list context
   

This ensures filters feel immediate, reversible, and safe.
 

3. Filters Popup – Visual & Functional Layout
 

The filters popup is divided into four functional tabs, each representing a different filtering strategy.
 

Advanced Filters
 

This is the main builder for most users.
It allows building a single logical filter composed of multiple conditions combined with AND / OR logic.
 

Saved Filters
 

This tab displays all previously saved advanced filters, allowing for immediate reuse, editing, or sharing.
 

Multiple Advanced Filters
 

This tab allows building score-based filters, where each condition contributes to a weighted evaluation.
 

Multiple Saved Filters
 

This tab stores and manages previously saved multi-criteria (score-based) filters.
 

At any time, "Clear All" resets the filter state and returns the list to its default view.
 

4. Advanced Filters – How to Build a Single Filter
 

Advanced filters are built row by row, with each row representing one condition.
 

Step 1: Select Field
 

The user selects a field from a dynamically generated dropdown list.

This list includes:
 

• Core system fields (email, phone, status, source, tags, etc.)

• Financial and status metrics

• Dates and timestamps

• Additional organization-defined fields

• Auto-expanding grouped custom fields
   

The field list is centrally generated so that the same fields are available everywhere.
 

Step 2: Select Condition
 

Each field can be tested using operators such as:
 

• Is

• Is Not

• Is Empty

• Is Not Empty
   

These operators are language-aware and consistent across the system.

 

Step 3: Enter Value
 

The value input adapts to the selected field type:
 

• Dropdowns for enums (status, tags, managers)

• Date pickers for dates

• Text input fields for strings

• Numeric input fields for amounts
   

Step 4: Combine Conditions
 

Users can add an unlimited number of rows and connect them using AND / OR logic, allowing for very precise queries.
 

5. Include Child Customers & Additional Options
 

Include Child Customers
 

A dedicated checkbox allows the filter to include sub-customers (child records).
 

This setting:
 

• Can be toggled for each filter

• Is saved within the filter definition

• Can also be enabled globally for each user
   

Additional Options
 

An "Additional Options" panel allows injecting extra key/value constraints that are not part of the main UI fields.
 

These options:
 

• Are saved along with the filter

• Migrate with saved filters

• Are transparently applied by the backend query engine
   

6. Activating a Filter – What Really Happens
 

When the user clicks Apply, the system doesn't just hide rows.
 

Instead, it performs a full data reload using a built-in filter payload.
 

Internally:
 

1. The UI builds a structured filter object

2. All selected fields, operators, values, AND/OR logic, additional options, and child flags are packaged

3. This payload is sent to the main loading API

4. The backend converts it into SQL filter logic

5. The customer list is reloaded using the filtered query
    

This ensures:
 

• Correct pagination

• Correct totals

• Correct exports

• Consistent results everywhere
   

7. Saving Filters – Persistent Views
 

Any advanced filter can be saved with a name.
 

Once saved:
 

• It appears in the Saved Filters tab

• It can be instantly reactivated

• It can be edited or overwritten

• It can be copied as a direct URL
   

Saved filters are scoped per user and per organization, ensuring privacy and consistency.
 

Opening the page with ?advance={filter_id} automatically activates that filter.
 

8. Multiple Advanced Filters – Scoring Logic
 

Multiple advanced filters extend filtering beyond simple yes/no logic.
 

Each condition:
 

• Has a comparison operator

• Has a value

• Contributes to a score
   

The final score determines if a customer matches.
 

This is ideal for:
 

• Lead qualification

• Priority ranking

• Complex business rules
   

Multiple saved filters behave exactly like single saved filters but use a different evaluation engine.
 

9. Backend Query Engine
 

All filtering logic ultimately passes through a single backend loader.
 

This loader:
 

• Reads filter parameters

• Dynamically constructs SQL WHERE clauses

• Applies correct AND/OR logic

• Merges multiple filters when present

• Handles additional options and sub-customers

• Ensures security and correctness
   

This unified engine ensures filters behave identically across:
 

• Customer list

• Tabs

• Orders

• Exports

• Reports
   

10. Database Persistence
 

Saved filters are stored in dedicated tables.
 

• Single filters store arrays of conditions, operators, values, and flags

• Multiple filters store scored conditions and additional metadata

• Filters are scoped by user, organization, and context (customer, tab, order)
   

This allows filters to be:
 

• Safely reused

• Transferred between contexts

• Automatically applied on export
   

11. Export Integration
 

The export system is filter-aware by design.
 

When exporting:
 

• The system uses the same filter query

• Folder, search, and filters are all taken into account

• Selected rows override filters if selected

• Saved filters can be exported directly by ID
   

This ensures exported files always match what the user sees.
 

12. Tabs, Orders & Reuse
 

The filtering system is reused across multiple modules.
 

• Tabs can have their own saved filters

• Orders use the same filter settings

• Newspaper and WhatsApp views use the same logic

• Only the context flag changes
   

This reuse prevents duplication and maintains logic consistency.
 

13. End-to-End Lifecycle


User opens filter
     ↓
Builds conditions
     ↓
Activates filter
     ↓
Backend builds query
     ↓
Customer list reloads
     ↓
(Optional) Saves filter
     ↓
Reuses / Exports / Shares


14. Why This System is Important
 

The filtering system is a central intelligence layer, not just a UI convenience.
 

It: