Cache Strategy & Keys
The application uses TanStack Query (React Query) for state management. This document lists all cache keys used in the frontend and the events that trigger their invalidation.
Global Strategy
Arguments such as filtering options (limit, offset, filters) are often part of the query key (e.g., ['cameras', { limit: 10 }]). Invalidation logic typically targets the root key (e.g., ['cameras']) to refresh all variations of the list.
Cache Keys Reference
1. Dashboard Keys
These keys drive the real-time analytics on the main dashboard. They are critical for ensuring the "single pane of glass" view remains accurate.
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['dashboard-summary'] | Total counts of entities (Cameras, Users, Sites, Companies). | CRUD on any entity (Create/Delete). |
['dashboard-detailed-metrics'] | Detailed status breakdown (Active/Inactive, Online/Offline). | CRUD on any entity; Status changes (e.g., Camera Start/Stop). |
['dashboard-cameras-status'] | Pie chart data for camera statuses (Online, Offline, Maintenance). | Camera Creation/Deletion; Camera Start/Stop actions; Camera Updates. |
['dashboard-recent-activity'] | List of recent actions (e.g., "Camera X created", "User Y updated"). | Any CRUD operation on any entity; Status changes. |
['dashboard-notifications'] | System notifications displayed in the dashboard widget. | Incoming WebSocket notification. |
['dashboard-trends', days] | Historical trend lines for agitation or system stats. | Automatic refetch (30s interval); not manually invalidated usually. |
['dashboard-system-metrics'] | Real-time system load, memory, and uptime. | Automatic refetch (30s interval). |
2. Domain Entity Keys
Cameras (features/cameras)
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['cameras'] | List of cameras (filtered or all). | Create/Update/Delete Camera; Start/Stop Stream; Start/Stop Script. |
['camera', id] | Details of a single camera. | Update Camera; Start/Stop Stream; Start/Stop Script. |
['camera-agitation-trends', id] | Agitation metrics history. | Automatic refetch; Page refresh. |
['camera-agitation-distribution', id] | Distribution charts. | Automatic refetch. |
Users (features/users)
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['users'] | List of users. | Create/Update/Delete User; Disable 2FA. |
['user', id] | Details of a single user. | Update User; Disable 2FA; Send Password Reset. |
Sites (features/sites)
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['sites'] | List of sites. | Create/Update/Delete Site; Add/Remove User from Site. |
['site', id] | Details of a single site. | Update Site. |
Companies (features/companies)
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['companies'] | List of companies. | Create/Update/Delete Company; Add/Remove User from Company. |
['company', id] | Details of a single company. | Update Company. |
3. Notification Keys
| Query Key | Description | Invalidation Triggers |
|---|---|---|
['notifications'] | User's personal notification history. | Incoming WebSocket notification. |
['notifications', 'unread-count'] | Count of unread notifications badge. | Incoming WebSocket notification. |
Invalidation Rules
To ensure data consistency, we follow these rules in our custom hooks (e.g., useCreateCamera, useDeleteUser):
- Always invalidate the list: When an item is created/deleted,
['entity-list']must be invalidated. - Always invalidate the detail: When an item is updated,
['entity', id]must be invalidated. - Cross-Domain Invalidation: Dashboard widgets depend on aggregate data. Every CRUD operation must invalidate:
['dashboard-summary'](if count changes)['dashboard-detailed-metrics'](if status counts change)['dashboard-recent-activity'](to show the action log)