# Performance Guidelines

> Optimization strategies and best practices for frontend and backend performance.

## 🚀 Frontend Performance

### JavaScript Performance

#### Bundle Optimization
- **Code Splitting**: Split code into smaller chunks
- **Tree Shaking**: Remove unused code from bundles
- **Module Loading**: Use dynamic imports for non-critical code

```javascript
// Dynamic imports for better performance
const LazyComponent = lazy(() => import('./LazyComponent.js'));

// Code splitting by route
const AdminPanel = lazy(() => import('./admin/AdminPanel.js'));
```

#### Runtime Performance
- **Debouncing/Throttling**: Limit expensive operations
- **Virtual Scrolling**: Handle large datasets efficiently
- **Memory Management**: Prevent memory leaks

```javascript
// Debounced search
const debouncedSearch = debounce((query) => {
  performSearch(query);
}, 300);

// Throttled scroll handler
const throttledScroll = throttle(() => {
  updateScrollPosition();
}, 16); // ~60fps
```

### CSS Performance

#### Critical CSS
- Inline critical CSS for above-the-fold content
- Load non-critical CSS asynchronously
- Use CSS containment for performance isolation

```css
/* Critical CSS - inline in <head> */
.hero-section {
  contain: layout style paint;
  /* Critical styles only */
}

/* Non-critical CSS - load async */
@import url('non-critical.css') (min-width: 768px);
```

#### Efficient Selectors
- Avoid complex selector chains
- Use class selectors over tag selectors
- Minimize reflows and repaints

```css
/* Efficient */
.card-title { color: var(--text-primary); }

/* Inefficient */
.card .content .title h2 { color: var(--text-primary); }
```

### Asset Optimization

#### Image Optimization
- Use appropriate formats (WebP, AVIF)
- Implement responsive images
- Add loading="lazy" for below-fold images

```html
<!-- Responsive images -->
<picture>
  <source srcset="image.avif" type="image/avif">
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="Description" loading="lazy">
</picture>
```

#### Font Loading
- Use font-display: swap
- Preload critical fonts
- Subset fonts to reduce file size

```css
@font-face {
  font-family: 'Inter';
  font-display: swap;
  src: url('inter-subset.woff2') format('woff2');
}
```

## ⚡ Backend Performance

### Database Optimization

#### Query Optimization
- Use indexes effectively
- Avoid N+1 queries with eager loading
- Implement connection pooling

```php
// Eager loading to prevent N+1
$users = $userRepository->findWithProfiles();

// Use database indexes
$users = $userRepository->findByEmailIndex('user@example.com');
```

#### Caching Strategies
- Redis for session and cache storage
- Database query result caching
- Fragment caching for expensive operations

```php
// Cache expensive operations
$result = $cache->remember('expensive-calculation', 3600, function() {
    return performExpensiveCalculation();
});
```

### HTTP Performance

#### Response Optimization
- Enable gzip/brotli compression
- Set appropriate cache headers
- Use CDN for static assets

```php
// Set cache headers
$response->headers->set('Cache-Control', 'public, max-age=3600');
$response->headers->set('ETag', $etag);
```

#### Connection Management
- HTTP/2 server push for critical resources
- Connection keep-alive
- Reduce HTTP requests through bundling

## 📊 Performance Monitoring

### Metrics Collection

#### Core Web Vitals
- **LCP**: Largest Contentful Paint < 2.5s
- **FID**: First Input Delay < 100ms
- **CLS**: Cumulative Layout Shift < 0.1

```javascript
// Measure Core Web Vitals
import { getCLS, getFID, getLCP } from 'web-vitals';

getCLS(console.log);
getFID(console.log);
getLCP(console.log);
```

#### Custom Metrics
- Time to Interactive (TTI)
- First Contentful Paint (FCP)
- Resource loading times

```javascript
// Custom performance marks
performance.mark('feature-start');
// ... feature implementation
performance.mark('feature-end');
performance.measure('feature-load', 'feature-start', 'feature-end');
```

### Performance Budget

#### Resource Budgets
- JavaScript: < 170KB gzipped
- CSS: < 50KB gzipped
- Images: < 500KB per page
- Total page weight: < 1MB

#### Timing Budgets
- First Byte: < 600ms
- First Contentful Paint: < 1.5s
- Largest Contentful Paint: < 2.5s
- Time to Interactive: < 3.8s

## 🔧 Tools & Testing

### Development Tools
- **Lighthouse**: Automated performance auditing
- **WebPageTest**: Real-world performance testing
- **Chrome DevTools**: Performance profiling

### Continuous Monitoring
- **Real User Monitoring (RUM)**: Actual user performance data
- **Synthetic Monitoring**: Automated performance tests
- **Performance Budgets**: CI/CD integration

```javascript
// Performance budget in CI
const budget = {
  resourceSizes: [
    { resourceType: 'script', budget: 170 },
    { resourceType: 'total', budget: 1000 }
  ],
  resourceCounts: [
    { resourceType: 'third-party', budget: 10 }
  ]
};
```

## 🎯 Optimization Checklist

### Frontend Checklist
- [ ] Critical CSS inlined
- [ ] JavaScript code split and lazy loaded
- [ ] Images optimized and responsive
- [ ] Fonts preloaded and optimized
- [ ] Service Worker implemented
- [ ] Performance metrics tracked

### Backend Checklist
- [ ] Database queries optimized
- [ ] Caching strategy implemented
- [ ] HTTP compression enabled
- [ ] CDN configured for static assets
- [ ] Database connections pooled
- [ ] Server monitoring active

### Monitoring Checklist
- [ ] Core Web Vitals tracked
- [ ] Performance budgets defined
- [ ] Real User Monitoring active
- [ ] Automated performance tests in CI
- [ ] Performance regression alerts set up

## 📈 Performance Patterns

### Progressive Enhancement
Build for performance from the ground up:

1. **Content First**: HTML loads fast
2. **Style Enhancement**: CSS loads progressively
3. **Interaction Layer**: JavaScript enhances experience
4. **Advanced Features**: Load only when needed

### Performance-First Architecture
- Minimal initial bundle size
- Lazy loading for secondary features
- Service Worker for offline functionality
- Resource prioritization for critical path

---

*For specific framework optimizations, see [Framework Performance](../framework/performance/README.md)*  
*For monitoring setup, see [Analytics System](../framework/analytics/README.md)*