FE+BE: performance improvements

This commit is contained in:
jokob-sk committed 2026-09-14 08:29:02 +10:00
1 parent cff3ddfc38
commit f52de6cbdc
23 files changed
+428 -31

No files matched your search

+29
View File
@@ -25,6 +25,8 @@ description: NetAlertX coding standards and conventions. Use this when writing c
- all code needs to be scalable to handle large networks with thousands of devices (10k+) without performance degradation
- no inline imports, all imports must be at the top of the file
- when using `server/logger.py` `mylog()`, only use valid levels: `none`, `minimal`, `verbose`, `debug`, `trace`; invalid levels silently degrade to `none`
- every Python function/method needs a succinct docstring describing its current use and behavior — not what changed or why (see Docstrings section below)
- before adding a new frontend language string, search `front/php/templates/language/en_us.json` for an existing key with the same text/purpose and reuse it — don't add a near-duplicate key just because it's needed on a new page (see Language Strings section below)
## File Length
@@ -80,6 +82,33 @@ Use timeNowUTC(as_string=False) for datetime operations (scheduling, comparisons
Use sanitizers from `server/helper.py` before storing user input. MAC addresses are always lowercased and normalized. IP addresses should be validated.
## Docstrings
Every Python function/method gets a docstring — one or two sentences, describing what it does and how it's used *right now*. Not a changelog:
```python
# Correct
def count_children_by_parent_mac(devices):
"""Return {parentMac: childCount} for the given device list, keyed by devParentMAC."""
# Wrong — narrates the diff instead of the current behavior
def count_children_by_parent_mac(devices):
"""Replaces the old get_number_of_children() to fix the O(n^2) scan."""
```
That history belongs in the commit message or PR description, not the docstring — it rots the moment the next change lands. Keep it succinct; only go past a couple of lines when the contract genuinely needs it (non-obvious return shape, units, a caller-visible side effect).
## Language Strings — Reuse Before Adding (DRY)
Before adding a new key to `front/php/templates/language/en_us.json`, grep it for an existing key with the same text or purpose and reuse that key instead of adding a near-duplicate:
```bash
grep -n "\"Gen_" front/php/templates/language/en_us.json # generic, reusable strings
grep -n "Next\|Previous\|Showing" front/php/templates/language/en_us.json
```
Prefer the generic `Gen_*` keys (e.g. `Gen_Prev`, `Gen_Next`) over a page-scoped name (`Presence_Page_Prev`) for genuinely generic UI text — a future page needing the same label should find it already there. Only add a new key when nothing existing fits; only that one file needs the addition — `getString()`/`lang()` fall back to the English string for any locale missing a key, so the other ~23 locale files don't need touching.
## Devcontainer Constraints
- Never `chmod` or `chown` during operations
@@ -0,0 +1,35 @@
---
name: netalertx-ux-design-patterns
description: Read before adding or changing any front/ UI element - a control, layout, button, or interaction pattern. Covers the don't-invent-new-UX-without-a-PRD rule and the priority order for design tradeoffs (existing behavior > intuitiveness > information density > usability > utility > uniqueness > industry practices > generic UI).
---
# UX / Frontend Design Patterns
## Core principle: reuse before inventing
Don't introduce new UX behavior or visual patterns unless a PRD explicitly calls for it. Before building any new UI element, search the existing frontend for a pattern that already solves this exact need, and reuse its markup/CSS/behavior instead of inventing a new one.
Real, recent example: a presence-page Prev/Next pager was first built with custom `<button class="btn btn-xs">` elements floated in a `.box-header`. The DataTables pagination pattern (`dataTables_wrapper` / `dataTables_paginate` / `ul.pagination` / `li.paginate_button.previous|next`) already existed elsewhere in the app and does the exact same job. The custom version looked visually broken in the actual UI and had to be reimplemented using the existing pattern once that was caught in manual testing - reusing it also picked up dark-mode theming (`front/css/dark-patch.css`'s `.pagination li > a` / `.disabled` rules) for free, which the hand-rolled version didn't have. Grep first: e.g. `grep -rn "pagination\|paginate_button" front/` before adding a "previous/next" control of your own; the same applies to modals, filter inputs, badges, tooltips, tables - anything that already has an established shape somewhere in `front/`.
## Priority order for design decisions
When several options are all locally reasonable, resolve the choice in this order - highest wins on conflict:
1. **Existing behavior** - what does this codebase already do for the same or a similar need? Copy it.
2. **Intuitiveness** - will a user already familiar with the rest of the app understand this without being told?
3. **Information density** - does it show what's needed without wasting space or hiding what matters?
4. **Usability** - is it easy and low-friction to actually use (reachability, click count, error tolerance)?
5. **Utility** - does it solve the real problem, not just resemble a solution?
6. **Uniqueness** - is this the app's own distinct answer, used only where nothing generic fits well?
7. **Industry practices** - conventions users bring in from other apps.
8. **Generic UI** - a default/framework-provided look, used only when nothing above applies.
This list exists to end debates quickly, not to be argued from the bottom up. The reason it's written down is that #1 is exactly the step that gets skipped under time pressure - checking it first is meant to be fast, not a detour.
## Practical checklist before building a new UI element
1. Grep `front/js/`, `front/css/`, `front/php/` for an existing implementation of the same interaction - a table, a pager, a filter box, a modal, a badge, a status indicator.
2. If found, reuse its markup and CSS classes directly rather than writing new ones - matching classes inherit theming (dark mode, responsive breakpoints) a new hand-rolled version won't have.
3. If nothing fits, check whether the PRD driving this change actually calls for new UX. If it doesn't, that's a signal to look harder for an existing pattern, not license to invent one.
4. If a new pattern is genuinely warranted and the PRD says so, design it using the priority order above, and record the choice and why existing patterns didn't fit in the PRD - the next change will hit the same fork and shouldn't have to re-derive the answer.
5. Verify visually in a real browser/devcontainer before calling it done. A change that "should work" per the markup isn't confirmed until it's actually rendered - matches the project's general "test the golden path in a browser" rule for frontend changes.