# Frontend standards

## Architecture

Recommended modules:

```text
app-shell
auth
routing
i18n
design-system
dashboards
widgets
metrics
inventory
alerts
incidents
events
settings
operations
```

Feature modules own routes, queries, views and tests. Shared UI remains domain-neutral.

## State

- URL state for shareable filters/time range when appropriate.
- Server state via TanStack Query or measured equivalent.
- Editor draft state isolated from saved dashboard state.
- WebSocket subscriptions managed by one client/service.
- Chart samples in bounded local stores/ring buffers.
- Avoid duplicating server state across stores.

## Dashboard editor

- Save complete version atomically.
- Use explicit edit session/draft.
- Detect optimistic concurrency conflict.
- Undo/redo operates on normalized editor commands or bounded snapshots.
- Breakpoint layouts validated before save.
- Keyboard move/resize and screen-reader labels.
- Prevent accidental drag from chart interactions.

## Charts

- Lazy-load heavy chart implementations.
- Initialize history once per query.
- Append live data efficiently.
- Cap points/series.
- Dispose observers/listeners/instances.
- Pause offscreen/background work.
- Provide textual summary/table alternative.
- Use consistent units, timestamps, legend and tooltip behavior.
- Status thresholds do not overwrite data meaning.

## Tables/lists

- Cursor/server pagination for large datasets.
- Virtualization for large rendered collections.
- Stable row keys.
- Accessible sorting/filtering labels.
- Preserve filter state sensibly.
- Loading and empty states are distinct.

## Error handling

- Route-level boundary.
- Component/query errors show safe, actionable messages.
- Correlation ID exposed for diagnostics.
- Retry only when safe and bounded.
- Authentication expiry has a clean flow.
- Partial datasource failure does not blank the entire app.

## Styling

- Use design tokens; no scattered literal colors/spacing.
- Consistent card padding and grid gaps.
- Limited elevation.
- Status colors only for status.
- Respect reduced motion.
- Avoid oversized decorative headers that reduce information space.
- Desktop and mobile screenshots/visual regression for key routes.

## Testing

- Unit tests for formatting/transforms/editor reducers.
- Component tests for states and accessibility.
- Playwright for user journeys.
- Axe or equivalent on all core routes and viewports.
- Real browser verification for drag/resize, WebSocket reconnect and wallboard.
- Leak/soak instrumentation for chart/subscription lifecycle.