State Management & Query Caching
Relevant source files
The following files were used as context for generating this wiki page:
State management and query caching within the Coastal Charm BNB platform are primarily handled through TanStack Query (React Query) for server state and a custom CMS Caching Layer for headless content. This dual-layered approach ensures that high-frequency operational data (like RFQs and project bids) remains synchronized with the Supabase backend, while less volatile content (like FAQs and testimonials) is served efficiently from a client-side cache.
The system prioritizes real-time data consistency through query invalidation and specialized hooks, alongside local persistence strategies for complex form data to prevent data loss during the creation process.
Server State Management
The application leverages TanStack Query to manage the lifecycle of asynchronous data fetched from Supabase. This includes automatic caching, background refetching, and state synchronization across components.
Query and Mutation Architecture
Components utilize useQuery for data retrieval and useMutation for data modification. After successful mutations, the useQueryClient is utilized to invalidate specific query keys, forcing a refresh of the cached data to ensure UI consistency.
The diagram above illustrates the TanStack Query lifecycle and the invalidation process used to maintain data freshness.
Key Implementation Details:
- Query Invalidation: When an RFQ is saved or updated, the system invalidates keys such as
['rfqs'],['rfq-edit', id], and['rfq-properties', id]to trigger re-fetching.- Sources:
[src/pages/admin/RFQEdit.tsx:645-649](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/pages/admin/RFQEdit.tsx#L645-L649)
- Sources:
- Background Subscriptions: Hooks like
useRFQSubscriptionanduseRFQListSubscriptionprovide real-time updates to the query cache when external changes occur in the database.- Sources:
[src/pages/admin/ComprehensiveRFQDetail.tsx:24](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/pages/admin/ComprehensiveRFQDetail.tsx#L24),[src/pages/admin/UnifiedRFQManagement.tsx:16](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/pages/admin/UnifiedRFQManagement.tsx#L16)
- Sources:
Performance Optimization
To enhance query speed, the backend implementation includes 8 performance indexes. Post-migration benchmarks indicate query performance improvements ranging from 10x to 100x for complex tables like vendor_bids and leases.
- Sources:
[DEPLOYMENT_GUIDE.md:214-220](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/DEPLOYMENT_GUIDE.md#L214-L220)
Client-Side CMS Caching
For content-heavy sections such as FAQs, services, and testimonials, a custom CMSClient implements an in-memory caching mechanism to reduce redundant API calls to headless CMS providers.
CMS Cache Configuration
The CMSClient uses a TTL (Time-To-Live) strategy to manage cache expiration.
| Parameter | Value | Description |
|---|---|---|
| Storage Mechanism | Map<string, { data: unknown; timestamp: number }> | In-memory key-value store for content objects. |
| Default TTL | 300,000ms (5 minutes) | Duration before cached content is considered stale. |
| Cache Keys | page:[slug], faqs:[category], services | Specific identifiers for different content types. |
- Sources:
[src/lib/cms.ts:50-54](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/lib/cms.ts#L50-L54)
CMS Data Flow
The getFromCache method checks the timestamp of stored data against the current time. If the difference exceeds the cacheTTL, the entry is deleted and a fresh fetch is initiated.
Sequence diagram showing the logic for retrieving data through the CMS caching layer.
- Sources:
[src/lib/cms.ts:184-206](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/lib/cms.ts#L184-L206)
Persistence and Autosave Strategies
For long-form data entry, specifically in the RFQ creation module, the platform implements local persistence to bridge the gap between volatile component state and permanent database storage.
Local Draft Persistence
The useAutosave hook is employed to store unsaved form data in the browser's local storage. This allows users to recover their work if the browser is refreshed or closed unexpectedly.
- Storage Key:
rfq-create-detailed-draft - Autosave Frequency: 1500ms delay after data changes.
- Auto-save to DB: The system also triggers a background database save after 30 seconds of inactivity if the RFQ is in 'draft' status.
- Sources:
[src/pages/admin/RFQEdit.tsx:160-165](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/pages/admin/RFQEdit.tsx#L160-L165),[src/pages/admin/RFQEdit.tsx:694-712](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/pages/admin/RFQEdit.tsx#L694-L712)
Query Performance Testing
The system includes utilities to measure and validate query performance and RLS (Row-Level Security) policy enforcement to ensure the state management layer is both secure and performant.
Performance Thresholds
The testQueryPerformance utility validates that queries complete within defined timeframes:
| Query Name | Threshold | Description |
|---|---|---|
| Vendor Profiles | 1000ms | Basic selection with limit. |
| Projects with Relations | 1500ms | Complex joins (e.g., milestones). |
| Security Aggregation | 2000ms | Large dataset filtering by date. |
- Sources:
[src/utils/testUtilities.ts:135-155](https://github.com/ZachMonarch/coastal-charm-bnb/blob/69e59eabb3d5d52cfdf9ff094ab1d61c5bd2df75/src/utils/testUtilities.ts#L135-L155)
Summary
The state management architecture of the Coastal Charm BNB platform effectively separates volatile server state from static content. By utilizing TanStack Query for operational data, the application ensures real-time consistency and high performance through intelligent invalidation and database indexing. Complementary to this, the CMS Caching Layer and Local Persistence strategies provide a resilient and responsive user experience, minimizing API overhead and protecting user progress during complex workflows.