pgsql-jellyfin/docs/ASYNC_CONVERSION_PRIORITY.md

Repository Async Conversion Priority List

Based on analysis of 1,189 synchronous database operations found in the codebase.

📊 Priority Matrix

Priority determined by:

• Complexity: Lower is better (fewer operations, simpler logic)
• Impact: Higher is better (frequently used, performance-critical)
• Dependencies: Fewer dependencies = higher priority

✅ Phase 1: Simple Repositories (POC Complete + Easy Wins)

1. KeyframeRepository ✅ COMPLETED - POC

• Sync Operations: 3
• Complexity: ⭐ Very Low
• Files Changed: 3
  • IKeyframeRepository.cs
  • KeyframeRepository.cs
  • KeyframeManager.cs + interface
  • CacheDecorator.cs (sync wrapper needed)
• Status: ✅ CONVERTED
• Build: ✅ PASSING
• Notes: One method (TryExtractKeyframes) remains sync by interface design

2. MediaAttachmentRepository ✅ COMPLETED - POC

• Sync Operations: 5
• Complexity: ⭐⭐ Low
• Estimated Effort: 2-3 days
• Files to Change: ~5
• API Impact: Minimal (internal use)
• Dependencies: Low
• Recommendation: Do Next

3. MediaStreamRepository ✅ ✅ COMPLETED - POC

• Sync Operations: 5
• Complexity: ⭐⭐ Low
• Estimated Effort: 2-3 days
• Files to Change: ~6
• API Impact: Low
• Dependencies: Low
• Recommendation: Do in Phase 1

4. ChapterRepository ✅ COMPLETED - POC

• Sync Operations: 6
• Complexity: ⭐⭐ Low-Medium
• Files Changed: 6*.md
  • IChapterRepository.cs
  • ChapterRepository.cs
  • IChapterManager.cs
  • ChapterManager.cs
  • ChapterImagesTask.cs
  • DtoService.cs
• Status: ✅ CONVERTED
• Build: ✅ PASSING
• API Impact: Medium (chapter API endpoints)
• Dependencies: Medium

⚡ Phase 2: Medium Complexity

5. PeopleRepository ✅ COMPLETED - POC

• Sync Operations: 15
• Complexity: ⭐⭐⭐ Medium
• Estimated Effort: 1 week
• Files to Change: ~15
• API Impact: Medium-High (people/actors endpoints)
• Dependencies: Medium (used by BaseItemRepository)
• Recommendation: Do in Phase 2

🔥 Phase 3: Complex (High Impact, High Risk)

6. BaseItemRepository ⚠️

• Sync Operations: 110
• Complexity: ⭐⭐⭐⭐⭐ Very High
• Estimated Effort: 4-6 weeks
• Files to Change: 50+
• API Impact: 🔴 CRITICAL (All item endpoints)
• Dependencies: 🔴 VERY HIGH (Core of Jellyfin)
• Recommendation: DO LAST - Needs careful planning
• Special Notes:
  • Central to all library operations
  • Used by nearly every API endpoint
  • Requires extensive testing
  • Consider breaking into smaller pieces

---

📅 Recommended Timeline

Sprint 1-2: Simple Repositories ✅ COMPLETE (3-4 weeks)

• ✅ KeyframeRepository (DONE)
• ✅ MediaAttachmentRepository (DONE)
• ✅ MediaStreamRepository (DONE)
• ✅ ChapterRepository (DONE)

Goal: ✅ ACHIEVED - Gained experience, established patterns, validated approach

Sprint 3-4: Medium Complexity ⏳ NEXT (4 weeks)

• Week 1-3: PeopleRepository conversion
• Week 4: Integration testing, bug fixes

Goal: Test patterns with more complex scenarios

Sprint 5-10: BaseItemRepository (6 weeks)

• Week 1-2: Planning, breaking down into modules
• Week 3-5: Conversion in phases
• Week 6: Testing, performance validation

Goal: Complete core conversion with minimal disruption

---

🎯 Conversion Order Rationale

Why This Order?

1. KeyframeRepository First (✅ Done)

   • Smallest scope for POC
   • Low risk - not heavily used
   • Validates async patterns
   • Builds team confidence

2. Media*Repository Next

   • Still simple but more commonly used
   • Tests pattern on slightly larger scope
   • Related functionality (easier to reason about)

3. ChapterRepository After

   • Medium complexity
   • Has API endpoints (tests full stack)
   • Good transition to Phase 2

4. PeopleRepository Mid-Game

   • More complex queries
   • Used by BaseItemRepository
   • Must be done before BaseItemRepository

5. BaseItemRepository Last

   • Most complex
   • Highest risk
   • By now, team has experience
   • Patterns are well-established

---

📋 Detailed Conversion Steps

For each repository, follow this process:

1. Preparation (1 day)

• Read current implementation
• Identify all public methods
• Map all consumers (where it's used)
• List required interface changes
• Create feature branch

2. Interface Updates (0.5 days)

• Update interface with async methods
• Add CancellationToken parameters
• Update XML documentation

3. Implementation (1-3 days depending on complexity)

• Convert repository methods to async
• Update all database operations
• Add proper async disposal (await using)
• Add ConfigureAwait(false) where appropriate

4. Consumer Updates (1-2 days)

• Update service layer
• Update API controllers
• Update background services

5. Testing (1-2 days)

• Update unit tests
• Update integration tests
• Add cancellation tests
• Performance testing

6. Review & Merge (0.5 days)

• Code review
• Fix any issues
• Merge to main

---

🔍 Detailed Repository Analysis

MediaAttachmentRepository

Sync Operations Found: 5

• ToList(): 3 instances
• ToArray(): 1 instance
• SaveChanges(): 1 instance

Files That Use It:

• MediaSourceManager.cs
• EncodingHelper.cs
• API controllers for media info

Breaking Changes:

• GetAttachmentStreams(Guid itemId) → GetAttachmentStreamsAsync(...)
• SaveAttachments(...) → SaveAttachmentsAsync(...)

Estimated Changes: 5-7 files

---

MediaStreamRepository

Sync Operations Found: 5

• ToList(): 3 instances
• SaveChanges(): 2 instances

Files That Use It:

• MediaSourceManager.cs
• MediaInfoManager.cs
• Playback state management

Breaking Changes:

• GetMediaStreams(Guid itemId) → GetMediaStreamsAsync(...)
• SaveMediaStreams(...) → SaveMediaStreamsAsync(...)

Estimated Changes: 6-8 files

---

ChapterRepository

Sync Operations Found: 6

• ToList(): 4 instances
• ExecuteDelete(): 1 instance
• SaveChanges(): 1 instance

Files That Use It:

• ChaptersController.cs (API)
• ChapterManager.cs
• MediaSourceManager.cs

Breaking Changes:

• GetChapters(Guid itemId) → GetChaptersAsync(...)
• SaveChapters(...) → SaveChaptersAsync(...)

API Endpoints Affected:

• GET /Items/{id}/Chapters
• POST /Items/{id}/Chapters

Estimated Changes: 8-10 files

---

PeopleRepository

Sync Operations Found: 15

• ToList(): 8 instances
• ToArray(): 4 instances
• FirstOrDefault(): 2 instances
• SaveChanges(): 1 instance

Files That Use It:

• PersonController.cs (API)
• BaseItemRepository.cs (⚠️ circular dependency)
• Various service layers

Breaking Changes:

• GetPeople(InternalPeopleQuery query) → GetPeopleAsync(...)
• GetPerson(string name) → GetPersonAsync(...)
• All people-related operations

API Endpoints Affected:

• GET /Persons
• GET /Persons/{name}
• People aggregations

Estimated Changes: 15-20 files

⚠️ Special Consideration: Used by BaseItemRepository, so must be done before Phase 3

---

BaseItemRepository ⚠️

Sync Operations Found: 110

• ToList(): 45+ instances
• ToArray(): 35+ instances
• FirstOrDefault(): 15+ instances
• ExecuteDelete(): 8 instances
• SaveChanges(): 5 instances
• BeginTransaction(): 2 instances

Files That Use It:

• Nearly every API controller
• LibraryManager.cs (core)
• All media scanning services
• All playback services
• Search functionality
• Filtering/sorting

Breaking Changes:

• 🔴 40+ public methods need conversion
• All item CRUD operations
• All query operations
• All aggregations

API Endpoints Affected:

• 🔴 100+ endpoints directly or indirectly
• All item retrieval
• All filtering/search
• All library browsing

Estimated Changes: 50-100 files

⚠️ Critical Notes:

• Core of entire application
• Must be done in phases
• Requires feature flags for gradual rollout
• Extensive testing required
• Consider performance impact
• May need database connection pool adjustments

Suggested Sub-Phases for BaseItemRepository:

1. Phase 3a: Query-only operations (GetItems, filters)
2. Phase 3b: Item retrieval (RetrieveItem, GetItem)
3. Phase 3c: Write operations (SaveItems, UpdateItems)
4. Phase 3d: Delete operations (DeleteItem)
5. Phase 3e: Aggregations and statistics

---

🧪 Testing Strategy Per Phase

Phase 1: Simple Repositories

• Unit Tests: All repository methods
• Integration Tests: Repository → Service layer
• Performance Tests: Basic benchmarks

Phase 2: Medium Complexity

• Unit Tests: All repository methods + edge cases
• Integration Tests: Full stack (Repository → Service → API)
• Performance Tests: Detailed benchmarks
• Load Tests: Concurrent operations

Phase 3: BaseItemRepository

• Unit Tests: Comprehensive coverage
• Integration Tests: End-to-end scenarios
• Performance Tests: Extensive benchmarking
• Load Tests: Production-like loads
• Stress Tests: Breaking point analysis
• Regression Tests: Ensure no behavioral changes
• Canary Deployment: Test with real users gradually

---

📊 Risk Assessment

Repository	Complexity	API Impact	Test Coverage	Overall Risk
KeyframeRepository	⭐	Low	Good	🟢 LOW
MediaAttachmentRepository	⭐⭐	Low	Good	🟢 LOW
MediaStreamRepository	⭐⭐	Low	Good	🟢 LOW
ChapterRepository	⭐⭐⭐	Medium	Good	🟡 MEDIUM
PeopleRepository	⭐⭐⭐	Medium	Medium	🟡 MEDIUM
BaseItemRepository	⭐⭐⭐⭐⭐	🔴 Critical	Needs More	🔴 HIGH

---

✅ Success Metrics

Per Repository:

• All sync operations converted
• All tests passing
• No performance regression (<5% slower)
• Build successful
• Code review approved

Overall Project:

• 100% async database operations
• PostgreSQL multiplexing enabled
• 20-40% reduction in connection pool usage
• No API breaking changes (async signatures OK)
• Documentation updated

---

🚀 Next Steps

1. ✅ Phase 1 COMPLETE: All simple repositories converted (4/4)
2. ✅ Pattern Established: Repeatable async conversion process
3. ✅ Documentation Complete: Comprehensive guides and presentations
4. Present Results: Show Phase 1 completion to stakeholders
5. Begin Phase 2: Start PeopleRepository conversion (~1 week)
6. Phase 2 Review: Evaluate progress, adjust approach

---

Document Version: 2.0
Last Updated: 2025-01-15
Status: Phase 1 Complete ✅ | Phase 2 Ready 🚀
Next Action: Present to Stakeholders, then Begin PeopleRepository