Performance Optimization
Relevant source files
The following files were used as context for generating this wiki page:
Performance Optimization in the Monarch Property Management project is a multi-layered system designed to achieve Core Web Vitals targets: Largest Contentful Paint (LCP) under 2.5s, Cumulative Layout Shift (CLS) under 0.1, and Interaction to Next Paint (INP) under 200ms. The architecture spans from low-level DOM utilities and network prefetching to high-level monitoring components and automated validation scripts.
The system focuses on minimizing main-thread blocking, optimizing resource delivery through critical path analysis, and providing real-time diagnostic feedback to developers and administrators. This is achieved through a combination of proactive optimizations (like lazy loading and debouncing) and reactive monitoring (Web Vitals tracking and system diagnostics).
Sources: src/lib/performanceOptimizations.ts:1-5, src/utils/performanceMonitoring.ts:1-10, scripts/performance-validation.sh:58-62
Core Optimization Utilities
The project utilizes a centralized performanceOptimizer and specific DOM utilities to manage expensive operations and prevent layout thrashing.
Computational Efficiency
The system implements standard patterns for throttling, debouncing, and memoization to reduce CPU overhead. Debouncing is specifically targeted at search inputs and API calls, while throttling is used for high-frequency events like scrolling.
Sources: src/utils/performanceOptimizer.ts:3-40
DOM and Layout Optimization
To prevent "Forced Reflows" (layout thrashing), the project provides utilities to batch DOM reads and writes. By using requestAnimationFrame, writes are synchronized with the browser's paint cycle.
Sources: src/utils/preventForcedReflow.ts:1-24
The diagram above illustrates the batching logic used to prevent layout thrashing.
Sources: src/utils/preventForcedReflow.ts:26-38, src/utils/performanceOptimizer.ts:56-60
Resource Management and Loading
The project optimizes the loading of assets (fonts, images, and scripts) through prefetching, preconnecting, and lazy loading strategies.
Network and Prefetching
Critical connections to external services like Supabase and Google Fonts are established early using preconnect and dns-prefetch hints in the document head.
Sources: index.html:7-17
| Method | Target | Purpose |
|---|---|---|
preconnect | Supabase, Google Fonts | Early socket establishment |
dns-prefetch | Stripe, GPT Engineer | Fallback for DNS resolution |
preload | Hero Images, Fonts | Prioritizing critical LCP assets |
prefetch | Secondary Routes | Warming up future navigation |
| Sources: index.html:7-21, index.html:190-205, src/lib/performanceOptimizations.ts:46-51 |
Image Optimization
Images are managed via two primary strategies:
- Lazy Loading: An
IntersectionObserveris used to load images only when they enter the viewport. - Aggressive Optimization: URLs are transformed to force WebP format and cap dimensions (e.g., width 800px) to save bandwidth.
Sources: src/utils/performanceOptimizer.ts:42-54, src/utils/performanceOptimizer.ts:79-92, src/lib/performanceOptimizations.ts:18-38
Performance Monitoring and Diagnostics
Monitoring is split between background tracking of Core Web Vitals and an administrative diagnostic interface.
Unified Performance Monitor
The UnifiedPerformanceMonitor component centralizes the tracking of key browser metrics using the PerformanceObserver API. It logs data for LCP, FID, CLS, INP, and TTFB.
Sources: src/components/UnifiedPerformanceMonitor.tsx:18-110
The sequence diagram shows how the monitoring component intercepts browser events to track performance ratings.
Sources: src/components/UnifiedPerformanceMonitor.tsx:30-80, src/utils/performanceMonitoring.ts:34-52
System Diagnostics Interface
The SystemDiagnostics component provides a dashboard for real-time health checks. It categorizes metrics into "System Health", "Performance", and "Security".
Sources: src/components/SystemDiagnostics.tsx:120-200
| Metric Category | Targets | Ideal State |
|---|---|---|
| Core Web Vitals | LCP, FID, CLS | "Good" (Green) |
| System Health | Memory, Network, Bundle | < 70% Memory, < 100ms Latency |
| Resource Load | CSS, JS, Images | Minimized, Optimized, Lazy-loaded |
| Sources: src/components/SystemDiagnostics.tsx:43-90, src/components/SystemDiagnostics.tsx:216-240 |
Validation Scripting
Automated performance validation is handled via a Lighthouse CLI script (performance-validation.sh). This script audits key pages (Home, Dashboard, Gallery) against defined target scores.
# Target scores defined in validation script
TARGET_PERFORMANCE=90
TARGET_ACCESSIBILITY=100
TARGET_BEST_PRACTICES=100
TARGET_SEO=90
Sources: scripts/performance-validation.sh:58-62
Summary
The performance optimization system provides a comprehensive framework for maintaining a fast, responsive property management platform. By leveraging browser APIs for both optimization (IntersectionObserver, requestAnimationFrame) and monitoring (PerformanceObserver), the project ensures that high-quality user experiences are maintained across all device types. Key utilities like the performanceOptimizer and the UnifiedPerformanceMonitor work in tandem to minimize latency and maximize interface stability.
Sources: src/utils/performanceOptimizer.ts:1-2, src/components/UnifiedPerformanceMonitor.tsx:12-17, src/utils/preventForcedReflow.ts:1-5