ObsiViewer/docs/PERFORMENCE/phase2/INTEGRATION_CHECKLIST.md

Phase 2 Integration Checklist

Pre-Integration Verification

• All files created successfully
• No compilation errors
• Server starts without errors: npm run dev
• Pagination endpoint responds: npm run test:pagination

Integration Steps

Step 1: Identify Parent Component (5 min)

• Locate the component that currently uses NotesListComponent
• Note the file path (e.g., src/app/layout/sidebar.component.ts)
• Document current inputs and outputs

Step 2: Update Imports (5 min)

File: Your parent component

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

// Add to @Component imports array
imports: [
  // ... existing imports
  PaginatedNotesListComponent
]

• Import added
• No import errors

Step 3: Update Template (5 min)

File: Your parent component template

Before:

<app-notes-list
  [notes]="notes()"
  [folderFilter]="selectedFolder()"
  [query]="searchQuery()"
  [tagFilter]="selectedTag()"
  [quickLinkFilter]="quickLinkFilter()"
  (openNote)="onNoteSelected($event)"
  (queryChange)="onSearchChange($event)"
  (clearQuickLinkFilter)="onClearQuickLink()">
</app-notes-list>

After:

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

Note: Remove [notes] input - pagination handles data loading automatically

• Template updated
• No template errors

Step 4: Update Event Handlers (5 min)

File: Your parent component TypeScript

Ensure these methods exist:

onNoteSelected(noteId: string) {
  // Navigate to note or update state
  this.router.navigate(['/note', noteId]);
}

onSearchChange(term: string) {
  // Update your search state if needed
  this.searchQuery.set(term);
}

onClearQuickLink() {
  // Clear quick link filter
  this.quickLinkFilter.set(null);
}

• onNoteSelected method exists
• onSearchChange method exists
• onClearQuickLink method exists

Step 5: Remove Old Data Loading (5 min)

File: Your parent component

Remove or comment out:

// OLD - No longer needed
private loadAllNotes() {
  this.http.get('/api/vault/metadata').subscribe(notes => {
    this.notes.set(notes);
  });
}

The pagination service handles all data loading automatically.

• Old data loading code removed/commented
• No references to old metadata endpoint

Step 6: Handle File Change Events (5 min)

File: Your vault event service (if you have one)

Add cache invalidation:

private handleFileChange(event: VaultEvent) {
  // Inject PaginationService
  private paginationService = inject(PaginationService);

  switch (event.type) {
    case 'add':
    case 'change':
    case 'unlink':
      // Invalidate pagination cache
      this.paginationService.invalidateCache();
      // Reload first page
      this.paginationService.loadInitial();
      break;
  }
}

• PaginationService injected
• Cache invalidation added
• File change handler updated

Step 7: Compile and Test (10 min)

# Terminal 1: Start dev server
npm run dev

# Terminal 2: Run tests
npm run test:pagination

• No compilation errors
• Dev server starts successfully
• npm run test:pagination passes all tests

Step 8: Manual Testing (10 min)

1. Open the app in browser

2. Scroll through notes list

   • List appears and is scrollable
   • Scrolling is smooth (60fps)
   • No jank or lag

3. Check network requests

   • Open DevTools → Network tab
   • Scroll to bottom of list
   • Should see requests to /api/vault/metadata/paginated
   • Each request loads ~100 items

4. Test search

   • Type in search box
   • Results should update
   • Scrolling should load more results

5. Test filters

   • Tag filter works
   • Quick link filter works
   • Folder filter works

6. Test selection

   • Click on a note
   • Note should be selected
   • Navigation should work

Step 9: Performance Verification (10 min)

DevTools Performance Tab:

1. Open DevTools → Performance tab
2. Click Record
3. Scroll through list for 10 seconds
4. Stop recording
5. Check results:
   • FPS stays at 60
   • No red bars (dropped frames)
   • No long tasks

DevTools Memory Tab:

1. Open DevTools → Memory tab
2. Take heap snapshot
3. Scroll through 1000+ items
4. Take another heap snapshot
5. Check:
   • Memory < 50MB
   • No memory leaks
   • Heap size stable

Step 10: Browser Compatibility (5 min)

Test in:

• Chrome/Chromium
• Firefox
• Safari
• Mobile browser (if applicable)

Rollback Plan (if needed)

If you need to revert to the old component:

1. Revert template to use app-notes-list
2. Restore old data loading code
3. Remove PaginatedNotesListComponent import
4. Restart dev server

The old endpoint /api/vault/metadata still works for backward compatibility.

Post-Integration

Monitor Performance

• Check browser console for errors
• Monitor memory usage over time
• Track scroll performance
• Verify search works correctly

Optimize if Needed

If performance is not as expected:

1. Adjust page size (default 100):

   // In pagination.service.ts
   const params: any = {
     limit: 50,  // Try smaller value
   };
   

2. Adjust item height (default 60px):

   <!-- In paginated-notes-list.component.ts -->
   <cdk-virtual-scroll-viewport itemSize="70">
   

3. Adjust preload threshold (default 20):

   // In paginated-notes-list.component.ts
   if (index > items.length - 10 && this.canLoadMore()) {
     // Load sooner
   }
   

Document Changes

• Update team documentation
• Add notes about new pagination behavior
• Document any configuration changes

Success Criteria

All of the following should be true:

• App compiles without errors
• Pagination endpoint works (npm run test:pagination)
• Notes list displays and is scrollable
• Scrolling is smooth (60fps)
• Search works with pagination
• Filters work correctly
• Memory usage < 50MB for 10k+ files
• No console errors
• No memory leaks
• Works on all target browsers

Estimated Time

• Pre-integration: 5 min
• Integration: 45 min
• Testing: 15 min
• Total: ~1 hour

Support

If you encounter issues:

1. Check the troubleshooting section in IMPLEMENTATION_PHASE2.md
2. Run npm run test:pagination to verify endpoint
3. Check browser console for errors
4. Review DevTools Network and Performance tabs
5. Verify Meilisearch is running: npm run meili:up

Files Modified

• src/app/features/list/paginated-notes-list.component.ts - New component
• src/app/services/pagination.service.ts - New service
• src/app/constants/pagination.config.ts - New config
• server/index.mjs - New endpoint
• package.json - New test script
• Your parent component - Updated imports and template

Files Not Modified

• Old NotesListComponent - Still works for backward compatibility
• Old /api/vault/metadata endpoint - Still works
• Other components - No changes needed

---

Ready to integrate? Follow the steps above and you'll have Phase 2 running in about 1 hour! 🚀