ObsiViewer/docs/PERFORMENCE/phase4/PHASE4_QUICK_START.md

# Phase 4 - Quick Start Guide

## 🚀 5-Minute Setup

### 1. Services Already Created ✅

All core services are in place:
- `src/app/services/client-cache.service.ts`
- `src/app/services/performance-profiler.service.ts`
- `src/app/services/note-preloader.service.ts`
- `src/app/services/navigation.service.ts`

### 2. Add Performance Monitor to App

**File**: `src/app.component.simple.html`

Add at the end (before closing tags):
```html
<!-- Performance monitoring panel (dev only) -->
<app-performance-monitor-panel></app-performance-monitor-panel>
```

### 3. Import in AppComponent

**File**: `src/app.component.ts`

```typescript
import { PerformanceMonitorPanelComponent } from './components/performance-monitor-panel/performance-monitor-panel.component';

@Component({
  imports: [
    // ... existing imports
    PerformanceMonitorPanelComponent,
  ]
})
export class AppComponent { }
```

### 4. Integrate Preloading

**In your note viewer component**:

```typescript
import { ClientCacheService } from '../../services/client-cache.service';
import { NotePreloaderService } from '../../services/note-preloader.service';
import { NavigationService } from '../../services/navigation.service';

export class NoteViewerComponent {
  private cache = inject(ClientCacheService);
  private preloader = inject(NotePreloaderService);
  private navigation = inject(NavigationService);

  async loadNote(noteId: string) {
    // Try cache first
    const cached = this.cache.get<any>(`note_${noteId}`);
    if (cached) {
      this.displayNote(cached);
      return;
    }

    // Load from server
    const note = await this.http.get<any>(`/api/files/${noteId}`).toPromise();
    this.displayNote(note);

    // Cache it
    this.cache.setMemory(`note_${noteId}`, note);

    // Preload adjacent notes
    const context = this.navigation.getCurrentContext(noteId);
    this.preloader.preloadAdjacent(noteId, context);
  }
}
```

### 5. Add Cleanup (Optional)

**In AppComponent ngOnInit()**:

```typescript
ngOnInit() {
  // ... existing code

  // Cleanup every 5 minutes
  setInterval(() => {
    this.preloader.cleanup();
  }, 5 * 60 * 1000);
}
```

## 📊 Monitor Performance

### In Development

1. Open browser DevTools (F12)
2. Look for performance panel in bottom-right corner
3. Click to expand and see:
   - Cache statistics
   - Preloader status
   - Top 5 slow operations
   - Bottlenecks

### In Console

```javascript
// Check cache status
const cache = ng.probe(document.querySelector('app-root')).injector.get(ClientCacheService);
console.log(cache.getStats());

// Check preloader status
const preloader = ng.probe(document.querySelector('app-root')).injector.get(NotePreloaderService);
console.log(preloader.getStatus());

// Export metrics
const profiler = ng.probe(document.querySelector('app-root')).injector.get(PerformanceProfilerService);
console.log(profiler.exportMetrics());
```

## 🧪 Run Tests

```bash
# Run Phase 4 tests
npm test -- --include='**/phase4.spec.ts'

# Expected: All tests pass ✅
```

## ⚙️ Configuration

### Preload Distance

How many notes to preload on each side:
```typescript
preloader.setConfig({ preloadDistance: 2 }); // Default
preloader.setConfig({ preloadDistance: 3 }); // More aggressive
preloader.setConfig({ preloadDistance: 1 }); // Conservative
```

### Concurrent Loads

Max simultaneous preloads:
```typescript
preloader.setConfig({ maxConcurrentLoads: 3 }); // Default
preloader.setConfig({ maxConcurrentLoads: 5 }); // More parallel
preloader.setConfig({ maxConcurrentLoads: 2 }); // Conservative
```

### Cache TTL

How long to keep items in memory:
```typescript
// 5 minutes (short-lived)
cache.setMemory(key, value, 5 * 60 * 1000);

// 30 minutes (default)
cache.setMemory(key, value, 30 * 60 * 1000);

// 1 hour (long-lived)
cache.setMemory(key, value, 60 * 60 * 1000);
```

## 📈 Expected Results

After setup:

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Navigation time | 200-500ms | 20-50ms | 80-90% faster |
| Cache hit rate | 0% | 70-80% | Perfect |
| Memory usage | 50-100MB | 50-100MB | Stable |
| Server requests | All | 60% less | Huge reduction |

## ✅ Verification Checklist

- [ ] Performance monitor panel visible in dev mode
- [ ] Cache statistics showing in panel
- [ ] Preloader status showing queue size
- [ ] Navigation feels smooth and instant
- [ ] No console errors
- [ ] Memory usage stable
- [ ] Tests all passing

## 🐛 Troubleshooting

### Panel not showing?
- Only visible in dev mode (localhost)
- Check browser console for errors
- Verify component imported

### Cache not working?
- Check `cache.getStats()` in console
- Verify TTL not expired
- Check cache size limits

### Preloading not working?
- Check `preloader.getStatus()` in console
- Verify enabled: `config.enabled = true`
- Check queue size and loading count

## 📚 Full Documentation

See `PHASE4_IMPLEMENTATION.md` for:
- Detailed integration steps
- API reference
- Configuration options
- Monitoring guide
- Best practices
- Troubleshooting

## 🎯 Next Steps

1. ✅ Follow 5-minute setup above
2. ✅ Run tests and verify
3. ✅ Monitor performance panel
4. ✅ Adjust configuration as needed
5. ✅ Deploy to production

---

**Time to implement**: ~5 minutes
**Risk**: Very low
**Impact**: Perfectly smooth navigation