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):

<!-- Performance monitoring panel (dev only) -->
<app-performance-monitor-panel></app-performance-monitor-panel>

3. Import in AppComponent

File: src/app.component.ts

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:

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():

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

// 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

# 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:

preloader.setConfig({ preloadDistance: 2 }); // Default
preloader.setConfig({ preloadDistance: 3 }); // More aggressive
preloader.setConfig({ preloadDistance: 1 }); // Conservative

Concurrent Loads

Max simultaneous preloads:

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:

// 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