ObsiViewer/docs/PERFORMENCE/phase2/QUICK_START_PHASE2.md

Phase 2 - Quick Start Guide

5-Minute Integration

1. Import the New Component

In your parent component (e.g., app-shell.component.ts):

import { PaginatedNotesListComponent } from './list/paginated-notes-list.component';

@Component({
  imports: [
    // ... existing imports
    PaginatedNotesListComponent
  ]
})
export class YourComponent {
  // Your code
}

2. Replace in Template

Before:

<app-notes-list
  [notes]="notes()"
  [folderFilter]="selectedFolder()"
  [query]="searchQuery()"
  (openNote)="onNoteSelected($event)">
</app-notes-list>

After:

<app-paginated-notes-list
  [folderFilter]="selectedFolder()"
  [query]="searchQuery()"
  (openNote)="onNoteSelected($event)"
  (queryChange)="onSearchChange($event)">
</app-paginated-notes-list>

3. Update Event Handler

onSearchChange(term: string) {
  // The pagination service handles loading automatically
  // Just update your UI state if needed
  this.searchQuery.set(term);
}

4. Test

# Terminal 1: Start the server
npm run dev

# Terminal 2: Test the endpoint
npm run test:pagination

Key Differences from Old Component

Feature	Old	New
Data loading	All at once	On demand
Memory usage	50-100MB	5-10MB
Scroll performance	Laggy	60fps smooth
Max files	~1000	10,000+
Search	Client-side	Server-side paginated

What Changed in the API

Old Endpoint

GET /api/vault/metadata
Response: [{ id, title, filePath, ... }, ...]

New Endpoint

GET /api/vault/metadata/paginated?limit=100&cursor=0&search=optional
Response: {
  items: [...],
  nextCursor: 100,
  hasMore: true,
  total: 12500
}

Note: The old endpoint still works for backward compatibility.

Verification Checklist

• New component imported
• Template updated to use app-paginated-notes-list
• Event handlers connected
• npm run test:pagination passes
• Scroll through notes list (should be smooth)
• Search works (should load pages as you scroll)
• No console errors

Rollback (if needed)

If you need to rollback to the old component:

1. Revert the template to use app-notes-list
2. Remove the import of PaginatedNotesListComponent
3. The old endpoint /api/vault/metadata still works

Performance Verification

Open DevTools (F12) and check:

1. Network tab: Should see requests to /api/vault/metadata/paginated
2. Performance tab: Scroll should maintain 60fps
3. Memory tab: Should stay under 50MB for 10k+ files

Next Steps

After integration:

1. Monitor performance in production
2. Adjust limit parameter if needed (default 100)
3. Adjust itemSize if your items have different height
4. Consider Phase 3 (server-side caching) for further optimization

Troubleshooting

Q: Pagination endpoint returns 500 error A: Run npm run meili:up && npm run meili:reindex

Q: Scroll is still laggy A: Check that virtual scrolling is working (DevTools → Performance tab)

Q: Search doesn't work A: Ensure onSearchChange is connected and calls paginationService.search()

Q: Items appear blank A: Verify itemSize="60" matches your actual item height

---

Ready to integrate? Follow the 4 steps above and you're done! 🚀