KArtSell.Aegis/frontend/PERFORMANCE_GUIDE.md

# Performance Optimization Guide

## Overview

This guide outlines performance best practices for the K-ArtSell Aegis frontend application.

## 1. Code Splitting

### Route-Based Code Splitting

All pages are lazy-loaded to reduce initial bundle size:

```typescript
// router.ts
import { defineAsyncComponent } from 'vue'

const ShadowRunQueue = defineAsyncComponent(() =>
  import('./features/shadow-run/pages/ShadowRunQueue.vue')
)
```

### Dynamic Imports

For large components, use dynamic imports:

```typescript
const HeavyComponent = defineAsyncComponent(() =>
  import('./components/HeavyComponent.vue')
)
```

## 2. Bundle Analysis

Check bundle size:

```bash
npm run build -- --report
```

Current budgets:
- Main bundle: < 200KB (gzipped)
- Vendor bundle: < 300KB (gzipped)
- Per-route chunk: < 50KB (gzipped)

## 3. Image Optimization

### Image Sizes

All images should be optimized before deployment:

```bash
# Optimize PNG
optipng -o2 image.png

# Optimize JPEG
jpegoptim --max=85 image.jpg

# Use WebP for modern browsers
cwebp image.png -o image.webp
```

### Lazy Loading

Use native lazy loading:

```html
<img src="image.jpg" loading="lazy" alt="Description" />
```

## 4. Caching Strategy

### Service Worker

Caching strategy (if enabled):
- Static assets: Cache indefinitely
- API responses: Network first, fallback to cache
- HTML: Network first, always

### Browser Caching

Headers set by server:
```
Cache-Control: max-age=31536000 (1 year) for /assets/*
Cache-Control: max-age=3600 (1 hour) for /index.html
```

## 5. Rendering Performance

### Virtual Scrolling

For large lists (>100 items), use virtual scrolling:

```vue
<virtual-scroller
  :items="items"
  :item-size="50"
  class="list-container"
>
  <template #default="{ item }">
    <div>{{ item.name }}</div>
  </template>
</virtual-scroller>
```

### Lighthouse Scores Target

Current targets (Lighthouse v10):
- **Performance**: 90+
- **Accessibility**: 95+
- **Best Practices**: 90+
- **SEO**: 90+
- **PWA**: 90+

## 6. Monitoring

### Core Web Vitals

Monitor these key metrics:
- **LCP** (Largest Contentful Paint): < 2.5s
- **FID** (First Input Delay): < 100ms
- **CLS** (Cumulative Layout Shift): < 0.1

### Performance API

```typescript
// Custom timing
performance.mark('operation-start')
// ... do work ...
performance.mark('operation-end')
performance.measure('operation', 'operation-start', 'operation-end')

const measure = performance.getEntriesByName('operation')[0]
console.log(`Operation took ${measure.duration}ms`)
```

## 7. Network Optimization

### HTTP/2 Server Push

Critical assets are pushed by server:
- `tokens.css`
- `main.js` (critical path)

### Compression

All text assets are gzip compressed (75% reduction typical).

## 8. Development Performance

### Vite Config

Current Vite settings for optimal DX:

```typescript
// vite.config.ts
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor': ['vue', 'vue-router', '@tanstack/vue-query'],
          'ui': ['@kbx/ui', 'primevue'],
        }
      }
    },
    minify: 'terser',
    target: 'esnext',
  }
}
```

### Build Metrics

```bash
# Analyze build time
npm run build -- --debug-time

# Expected: < 30s total build time
```

## 9. Checklist

Before deployment:

- [ ] Run Lighthouse audit (all scores ≥ 90)
- [ ] Test on 3G network (DevTools throttling)
- [ ] Verify images are optimized
- [ ] Check bundle size < limits
- [ ] Run E2E tests (all passing)
- [ ] Verify accessibility (axe audit)
- [ ] Test on real mobile device
- [ ] Monitor Real User Metrics (RUM)

## 10. References

- [Vite Performance](https://vitejs.dev/guide/features.html)
- [Vue Performance Guide](https://vuejs.org/guide/best-practices/performance.html)
- [Web Vitals](https://web.dev/vitals/)
- [Lighthouse](https://developers.google.com/web/tools/lighthouse)