Balancing Flexibility and User Experience: Building ArchGuard’s Insight Query Tool

When building software, developers constantly weigh flexibility against user experience; greater flexibility can lower change costs and improve deployment frequency, but may hurt end‑user usability. The author explores this tension while designing ArchGuard’s “Trend & Insight” feature, a mini data‑autonomy service resembling a lightweight data‑lake platform.

Version 1: UI‑Driven CRUD

The first implementation used a combination of dropdowns and input fields to let users construct queries. The workflow was:

UI generates data.

Backend validates the data and produces SQL.

SQL is executed and results returned.

Design relied on linked dropdowns and input validation. While practical and low‑learning‑cost, it suffered from overly complex inter‑field dependencies, endless requirement changes, and a lack of technical challenge, often resulting in bugs.

Version 2: Regex‑Based Field Matching

As the number of fields grew, the UI became unwieldy. The team switched to using the Monaco Editor as a single‑line input, generating SQL via regular‑expression matching. The process:

Dropdown + query string creates conditions.

Conditions are transformed into SQL.

SQL runs to produce data.

Data is filtered and returned.

Example of the generated rule: field: name == /.*log4j/ field: version >2.17.0 This approach introduced syntax highlighting, intelligent suggestions, and a theme (still pending). However, reliance on regex caused fragile user input handling and limited auto‑completion.

Developer Experience Boost: Monaco‑Based Search Box

Syntax highlighting for easier field entry.

Smart suggestions based on selected types.

Potential theming support.

Version 3: Custom Insight Query Language (DSL)

To decouple from MySQL and enable future MongoDB support, a thin abstraction layer called Insight Query Language was created. The DSL is a minimal SQL‑like language that parses queries, converts them to SQL, executes them, and returns filtered results.

Write DSL query.

Parser translates DSL to SQL.

Execute SQL to generate data.

Filter and return results.

Documentation is embedded directly in the editor, offering hover tooltips and auto‑suggestions to lower the learning curve. Completion logic analyses the current token (e.g., sca, dep_name, dep_version) and filters out already used fields, though front‑end updates can be slow.

Developer Experience Boost: Built‑in Documentation

Two main techniques are used:

Smart auto‑suggest : Syntax analysis drives context‑aware completions.

Embedded documentation : Hover and suggestion panels display literal type hints and supported formats.

Other Observations

The experimentation shows that better user experience often depends on better technical implementation, which in turn raises technical cost. The author invites readers to view the source code at https://github.com/archguard/archguard-frontend/tree/master/archguard/src/pages/insights.