# .NET 11.0 (PREVIEW) Upgrade Plan

## Table of Contents
1. [Executive Summary](#executive-summary)
2. [Migration Strategy](#migration-strategy)
3. [Detailed Dependency Analysis](#detailed-dependency-analysis)
4. [Project-by-Project Plans](#project-by-project-plans)
5. [Risk Management](#risk-management)
6. [Testing & Validation Strategy](#testing--validation-strategy)
7. [Complexity & Effort Assessment](#complexity--effort-assessment)
8. [Source Control Strategy](#source-control-strategy)
9. [Success Criteria](#success-criteria)

---

## Executive Summary

### Scenario Overview
This plan details the upgrade of the Jellyfin media server solution from .NET 9.0 to **.NET 11.0 (PREVIEW)**, encompassing 41 projects (40 application projects plus 1 analyzer project targeting netstandard2.0).

### Scope
- **Projects to Upgrade**: 40 projects (main codebase)
- **Projects Unchanged**: 1 project (Jellyfin.CodeAnalysis - netstandard2.0 analyzer)
- **Total Lines of Code**: Estimated 200,000+ LOC across solution
- **Project Types**: ASP.NET Core web applications, class libraries, test projects
- **Current Framework**: .NET 9.0 
- **Target Framework**: .NET 11.0 (PREVIEW)

### Discovered Metrics
- **Total Projects**: 41
- **Dependency Depth**: 12 levels (from leaf to top-level test projects)
- **Circular Dependencies**: None detected
- **Critical Path Length**: 12 project levels
- **NuGet Packages**: 80 total packages
- **Package Compatibility**: ✅ **100% compatible** - All packages already support .NET 11.0
- **Security Vulnerabilities**: None detected in current packages
- **Breaking Changes**: No mandatory breaking changes identified by assessment
- **Risk Indicators**: 
  - Large, complex solution with deep dependency chains
  - Preview framework (not production-ready)
  - Heavy use of Entity Framework Core and ASP.NET Core
  - Database providers (PostgreSQL, SQLite) require careful testing

### Complexity Classification: **Complex**

**Justification:**
- **42 projects** exceeds medium threshold (>15 projects)
- **12-level dependency depth** exceeds complexity threshold (>4 levels)
- **No high-risk issues** detected (0 mandatory issues)
- **No security vulnerabilities** in current packages
- **Complex technology stack**: EF Core, ASP.NET Core, multiple database providers, media processing
- **Preview framework target**: .NET 11.0 is not yet released (preview stability concerns)

Despite the absence of breaking changes or compatibility issues, the solution's **size, depth, and preview framework target** classify this as a **Complex** upgrade requiring careful, phased execution.

### Selected Strategy: Bottom-Up (Dependency-First) Approach

**Rationale:**
- **Large solution** (41 projects) benefits from incremental validation
- **Deep dependency tree** (12 levels) requires stable foundation before building upward
- **Preview framework** introduces unknown risks best addressed incrementally
- **Database providers** in mid-levels need thorough testing before application tier
- **Test projects** at multiple levels enable validation after each tier
- **Zero breaking changes** identified, but preview framework may introduce runtime issues
- **Risk-averse approach** appropriate for production media server moving to preview framework

### Critical Considerations
1. **Preview Framework**: .NET 11.0 is not production-ready; expect potential instability
2. **Package Ecosystem**: While packages report compatibility, preview framework behavior may differ
3. **Database Providers**: PostgreSQL and SQLite providers need extensive testing with .NET 11.0
4. **Media Processing**: SkiaSharp and media encoding libraries require validation
5. **Performance**: Monitor for performance regressions in preview builds
6. **Breaking Changes**: May emerge during testing despite clean analysis

### Expected Remaining Iterations
Based on complexity classification and solution structure:
- **Phase 1**: Complete (Discovery & Classification)
- **Phase 2**: 3 iterations (Foundation planning)
- **Phase 3**: 8-10 iterations (Tier-by-tier detailed planning)
- **Total**: ~11-13 iterations to complete plan

## Migration Strategy

### Approach Selection: Bottom-Up (Dependency-First)

**Decision: Incremental tier-by-tier migration** starting from leaf nodes (Tier 2) progressing to top-level application (Tier 11) and tests (Tiers 12-13).

### Rationale for Bottom-Up Strategy

#### Why Bottom-Up is Optimal for This Solution

1. **Large Solution Scale**
   - 41 projects exceed threshold for coordinated migration (>15 projects)
   - Incremental approach reduces risk of simultaneous failures
   - Enables validation at each tier before proceeding

2. **Deep Dependency Hierarchy**
   - 12 levels of dependencies require stable foundation
   - Bottom-up ensures each project builds on already-upgraded, tested tier
   - No multi-targeting complexity (all projects move to .NET 11.0)

3. **Preview Framework Target**
   - .NET 11.0 is PREVIEW (not production-ready)
   - Unknown risks best addressed incrementally
   - Early tiers expose framework issues before touching applications
   - Allows retreat/adjustment if preview proves unstable

4. **Clear Dependency Structure**
   - DAG (no circular dependencies) enables clean bottom-up flow
   - Well-defined tiers with explicit between-tier dependencies
   - Each tier can be independently validated

5. **Critical Database Layer**
   - Database providers (Tier 6) require extensive testing
   - Must be stable before business logic (Tier 8+)
   - Early validation prevents cascading failures

6. **Test Projects Throughout**
   - Test projects in Tiers 3, 5, 7, 9, 12, 13 enable continuous validation
   - Each tier completion includes test execution
   - Fail-fast at lowest affected tier

### Alternative Approaches Considered

#### ❌ All-At-Once Migration
**Rejected because:**
- 41 projects too large for coordinated update
- Preview framework introduces unknown risks
- Single-shot approach would complicate debugging
- Complex solution requires staged validation

#### ❌ Top-Down (Application-First)
**Rejected because:**
- Would require multi-targeting all dependencies
- Increased complexity managing two framework versions
- Testing top tiers before infrastructure ready is risky
- Database providers must be stable before applications use them

### Bottom-Up Execution Principles

#### Strict Tier Ordering
1. ✅ **Must complete Tier N before starting Tier N+1**
2. ✅ **Tier completion = all projects built, tested, validated**
3. ✅ **No tier skipping** - even if tempting to fast-track
4. ✅ **Rollback at tier level** - if tier fails, revert entire tier

#### Within-Tier Execution
- **Projects within same tier can be upgraded in parallel** (no inter-dependencies)
- **Batch project file updates** for entire tier (single operation)
- **Batch package updates** for entire tier (single operation)
- **Test tier as a whole** before proceeding
- **Tier 8** (12 projects) is largest; can parallelize to speed up

#### Tier Completion Criteria
Each tier must meet criteria before proceeding:

1. **Build Success**
   - All projects in tier build without errors
   - All projects in tier build without warnings (target: zero warnings)

2. **Package Restoration**
   - All NuGet packages restore successfully
   - No package dependency conflicts

3. **Test Execution**
   - All test projects in tier pass (if tier contains tests)
   - Tests for lower tiers still pass (regression check)

4. **Code Quality**
   - No new compiler errors introduced
   - Code analysis passes (StyleCop, analyzers)

5. **Validation Review**
   - Manual review of any unexpected changes
   - Verification of preview framework behavior

### Dependency-Based Ordering Details

#### Foundation First (Tiers 2-4)
- **Tier 2**: Core infrastructure (Database.Implementations, Extensions, Keyframes)
- **Tier 3**: Data models (Jellyfin.Data)
- **Tier 4**: Shared models (MediaBrowser.Model)

**Rationale**: These are referenced by all higher tiers. Must be rock-solid.

#### Infrastructure & Providers (Tiers 5-7)
- **Tier 5**: Common utilities (MediaBrowser.Common)
- **Tier 6**: Database providers (PostgreSQL, SQLite), Naming
- **Tier 7**: Controller abstractions

**Rationale**: Database providers are critical infrastructure requiring extensive testing before business logic.

#### Business Logic (Tiers 8-10)
- **Tier 8**: Business logic, media processing, networking (12 projects)
- **Tier 9**: API layer and business tests (8 projects)
- **Tier 10**: Server implementations (2 projects)

**Rationale**: Business logic depends on stable infrastructure; can parallelize within Tier 8.

#### Applications & Tests (Tiers 11-13)
- **Tier 11**: Main application (Jellyfin.Server)
- **Tier 12**: Integration tests
- **Tier 13**: Final implementation tests

**Rationale**: Applications last; integration tests validate entire stack.

### Parallel vs. Sequential Execution

#### Sequential (Between Tiers)
- **All tiers execute sequentially** - Tier N+1 waits for Tier N completion
- **No exceptions** - even for small tiers
- **Validation between tiers** - ensures stability before proceeding

#### Parallel (Within Tier)
Projects within same tier can execute in parallel:

- **Tier 2** (3 projects): Can parallelize
- **Tier 3** (2 projects): Can parallelize
- **Tier 5** (3 projects): Can parallelize
- **Tier 6** (3 projects): Can parallelize
- **Tier 7** (2 projects): Can parallelize
- **Tier 8** (12 projects): **High parallelism potential** - largest tier
- **Tier 9** (8 projects): Can parallelize (all tests)
- **Tier 10** (2 projects): Can parallelize
- **Tier 12** (2 projects): Can parallelize

**Parallelization Guidelines:**
- Update project files for all tier projects simultaneously
- Run builds in parallel (if resources allow)
- Aggregate results before proceeding to tests
- Test tier as a cohesive unit (not per-project)

### Phase Definitions

The migration consists of **13 phases** (one per tier):

#### Phase 1: Core Infrastructure (Tier 2)
- **Projects**: 3
- **Focus**: Database implementations, extensions, keyframe encoding
- **Validation**: Unit tests in Tier 3

#### Phase 2: Data Layer (Tier 3)
- **Projects**: 2
- **Focus**: Data models, first test validation
- **Validation**: Jellyfin.MediaEncoding.Keyframes.Tests

#### Phase 3: Model Layer (Tier 4)
- **Projects**: 1
- **Focus**: Central model definitions
- **Validation**: Model tests in Tier 5

#### Phase 4: Common Utilities (Tier 5)
- **Projects**: 3
- **Focus**: Common utilities, model validation tests
- **Validation**: Jellyfin.Extensions.Tests, Jellyfin.Model.Tests

#### Phase 5: Database Providers (Tier 6)
- **Projects**: 3
- **Focus**: PostgreSQL, SQLite providers; naming
- **Validation**: Extensive database integration tests (manual + automated)

#### Phase 6: Controller Layer (Tier 7)
- **Projects**: 2
- **Focus**: Controller abstractions, naming tests
- **Validation**: Jellyfin.Naming.Tests

#### Phase 7: Business Logic (Tier 8)
- **Projects**: 12 (largest phase)
- **Focus**: Photos, drawing, networking, media encoding, providers, server infrastructure
- **Validation**: Controller tests + business logic validation

#### Phase 8: API & Tests (Tier 9)
- **Projects**: 8
- **Focus**: Jellyfin.Api and comprehensive test suite for Tier 8
- **Validation**: All Tier 9 tests pass

#### Phase 9: Server Implementation (Tier 10)
- **Projects**: 2
- **Focus**: Emby.Server.Implementations, Jellyfin.Api.Tests
- **Validation**: API tests pass

#### Phase 10: Main Application (Tier 11)
- **Projects**: 1
- **Focus**: Jellyfin.Server (main entry point)
- **Validation**: Application starts and responds

#### Phase 11: Integration Tests (Tier 12)
- **Projects**: 2
- **Focus**: End-to-end integration tests
- **Validation**: All integration tests pass

#### Phase 12: Final Validation (Tier 13)
- **Projects**: 1
- **Focus**: Jellyfin.Server.Implementations.Tests
- **Validation**: Complete solution test suite passes

#### Phase 13: Solution Validation
- **Projects**: All 40 upgraded projects
- **Focus**: Full solution build, all tests, smoke testing
- **Validation**: Comprehensive validation before completion

### Risk Mitigation for Bottom-Up Strategy

#### Early Failure Detection
- Tier 2-4 failures detected before touching 90% of solution
- Database provider issues (Tier 6) caught before business logic
- Test projects throughout enable continuous validation

#### Preview Framework Risks
- Tier 2 upgrade exposes .NET 11.0 preview issues earliest
- Can assess framework stability before committing all projects
- Option to pause/revert if preview proves problematic

#### Incremental Learning
- Early tiers teach team about .NET 11.0 behavior
- Lessons learned applied to later tiers
- Compilation/runtime patterns identified early

#### Staged Deployment
- Can deploy lower tiers to staging environment incrementally
- Early performance/compatibility testing
- Risk distributed across multiple phases vs. single big-bang

### Rollback Strategy

#### Tier-Level Rollback
- If Tier N fails validation:
  1. Revert all Tier N project file changes
  2. Restore Tier N packages to .NET 9.0 versions
  3. Validate Tiers 1-(N-1) still stable
  4. Analyze failure, adjust plan
  5. Retry Tier N

#### Solution-Level Rollback
- If preview framework proves unstable:
  1. Git revert to upgrade branch start
  2. Document .NET 11.0 PREVIEW issues
  3. Consider alternative target (.NET 10.0 LTS)

### Success Criteria Per Phase

Each phase must achieve:
1. ✅ All projects build without errors
2. ✅ All projects build without warnings
3. ✅ All test projects pass (100% pass rate)
4. ✅ No package dependency conflicts
5. ✅ Code analysis passes
6. ✅ Manual validation complete (for critical tiers)
7. ✅ Performance acceptable (for application tiers)

Only when all criteria met, proceed to next phase.

## Detailed Dependency Analysis

### Dependency Graph Structure

The Jellyfin solution exhibits a **12-level dependency hierarchy** with clear separation between infrastructure, domain, and application layers. The graph follows a bottom-up structure ideal for tier-based migration.

```
Tier 1 (Level 0): Foundation - Analyzer
  └─ Jellyfin.CodeAnalysis (netstandard2.0) - NO UPGRADE

Tier 2 (Level 1): Core Infrastructure
  ├─ Jellyfin.Database.Implementations
  ├─ Jellyfin.Extensions
  └─ Jellyfin.MediaEncoding.Keyframes

Tier 3 (Level 2): Data & Encoding
  ├─ Jellyfin.Data
  └─ Jellyfin.MediaEncoding.Keyframes.Tests

Tier 4 (Level 3): Model Layer
  └─ MediaBrowser.Model

Tier 5 (Level 4): Model Tests & Common Layer
  ├─ Jellyfin.Extensions.Tests
  ├─ Jellyfin.Model.Tests
  └─ MediaBrowser.Common

Tier 6 (Level 5): Domain & Database Providers
  ├─ Emby.Naming
  ├─ Jellyfin.Database.Providers.Postgres
  └─ Jellyfin.Database.Providers.Sqlite

Tier 7 (Level 6): Controller & Naming Tests
  ├─ Jellyfin.Naming.Tests
  └─ MediaBrowser.Controller

Tier 8 (Level 7): Business Logic & Drawing
  ├─ Emby.Photos
  ├─ Jellyfin.Controller.Tests
  ├─ Jellyfin.Drawing
  ├─ Jellyfin.Drawing.Skia
  ├─ Jellyfin.LiveTv
  ├─ Jellyfin.MediaEncoding.Hls
  ├─ Jellyfin.Networking
  ├─ Jellyfin.Server.Implementations
  ├─ MediaBrowser.LocalMetadata
  ├─ MediaBrowser.MediaEncoding
  ├─ MediaBrowser.Providers
  └─ MediaBrowser.XbmcMetadata

Tier 9 (Level 8): API & Business Tests
  ├─ Jellyfin.Api
  ├─ Jellyfin.Common.Tests
  ├─ Jellyfin.LiveTv.Tests
  ├─ Jellyfin.MediaEncoding.Hls.Tests
  ├─ Jellyfin.MediaEncoding.Tests
  ├─ Jellyfin.Networking.Tests
  ├─ Jellyfin.Providers.Tests
  └─ Jellyfin.XbmcMetadata.Tests

Tier 10 (Level 9): Server Implementation
  ├─ Emby.Server.Implementations
  └─ Jellyfin.Api.Tests

Tier 11 (Level 10): Main Application
  └─ Jellyfin.Server

Tier 12 (Level 11): Integration Tests
  ├─ Jellyfin.Server.Integration.Tests
  └─ Jellyfin.Server.Tests

Tier 13 (Level 12): Final Test Layer
  └─ Jellyfin.Server.Implementations.Tests
```

### Tier Grouping Strategy

Based on the Bottom-Up Strategy and dependency analysis, projects are grouped into **13 tiers** for migration:

#### Tier 1: Foundation Analyzer (NO MIGRATION)
- **Jellyfin.CodeAnalysis** (netstandard2.0)
- **Dependencies**: None
- **Used By**: All projects (build-time analyzer)
- **Rationale**: Remains on netstandard2.0 for broad compatibility

#### Tier 2: Core Infrastructure (3 projects)
- **Jellyfin.Database.Implementations**
- **Jellyfin.Extensions**
- **Jellyfin.MediaEncoding.Keyframes**
- **Dependencies**: Only Jellyfin.CodeAnalysis (unchanged)
- **Rationale**: Leaf nodes with no internal dependencies; database and extension infrastructure

#### Tier 3: Data Layer (2 projects)
- **Jellyfin.Data**
- **Jellyfin.MediaEncoding.Keyframes.Tests**
- **Dependencies**: Tier 2 projects only
- **Rationale**: Data models and first test validation point

#### Tier 4: Model Layer (1 project)
- **MediaBrowser.Model**
- **Dependencies**: Tier 2 (Extensions) + Tier 3 (Data)
- **Rationale**: Central model definitions used throughout solution

#### Tier 5: Common Layer (3 projects)
- **Jellyfin.Extensions.Tests**
- **Jellyfin.Model.Tests**
- **MediaBrowser.Common**
- **Dependencies**: Tiers 2-4
- **Rationale**: Common utilities and model validation tests

#### Tier 6: Naming & Database Providers (3 projects)
- **Emby.Naming**
- **Jellyfin.Database.Providers.Postgres**
- **Jellyfin.Database.Providers.Sqlite**
- **Dependencies**: Tiers 2-5
- **Rationale**: Critical database providers requiring extensive testing

#### Tier 7: Controller Layer (2 projects)
- **Jellyfin.Naming.Tests**
- **MediaBrowser.Controller**
- **Dependencies**: Tiers 2-6
- **Rationale**: Controller abstractions; naming validation

#### Tier 8: Business Logic (12 projects)
- **Emby.Photos**
- **Jellyfin.Controller.Tests**
- **Jellyfin.Drawing**
- **Jellyfin.Drawing.Skia**
- **Jellyfin.LiveTv**
- **Jellyfin.MediaEncoding.Hls**
- **Jellyfin.Networking**
- **Jellyfin.Server.Implementations**
- **MediaBrowser.LocalMetadata**
- **MediaBrowser.MediaEncoding**
- **MediaBrowser.Providers**
- **MediaBrowser.XbmcMetadata**
- **Dependencies**: Tiers 2-7
- **Rationale**: Largest tier; business logic, media processing, networking; can parallelize within tier

#### Tier 9: API & Tests (8 projects)
- **Jellyfin.Api**
- **Jellyfin.Common.Tests**
- **Jellyfin.LiveTv.Tests**
- **Jellyfin.MediaEncoding.Hls.Tests**
- **Jellyfin.MediaEncoding.Tests**
- **Jellyfin.Networking.Tests**
- **Jellyfin.Providers.Tests**
- **Jellyfin.XbmcMetadata.Tests**
- **Dependencies**: Tiers 2-8
- **Rationale**: API layer and comprehensive test coverage for Tier 8

#### Tier 10: Server Implementation (2 projects)
- **Emby.Server.Implementations**
- **Jellyfin.Api.Tests**
- **Dependencies**: Tiers 2-9
- **Rationale**: Main server implementation and API validation

#### Tier 11: Main Application (1 project)
- **Jellyfin.Server**
- **Dependencies**: Tiers 2-10
- **Rationale**: Entry point application; depends on all business logic

#### Tier 12: Integration Tests (2 projects)
- **Jellyfin.Server.Integration.Tests**
- **Jellyfin.Server.Tests**
- **Dependencies**: Tier 11 (Jellyfin.Server)
- **Rationale**: End-to-end application validation

#### Tier 13: Final Test Validation (1 project)
- **Jellyfin.Server.Implementations.Tests**
- **Dependencies**: Tier 12 (Integration.Tests)
- **Rationale**: Final validation of server implementations with integration context

### Critical Path Analysis

**Longest Dependency Chain:**
```
Jellyfin.CodeAnalysis (Level 0)
  → Jellyfin.Database.Implementations (Level 1)
    → Jellyfin.Data (Level 2)
      → MediaBrowser.Model (Level 3)
        → MediaBrowser.Common (Level 4)
          → Emby.Naming (Level 5)
            → MediaBrowser.Controller (Level 6)
              → Jellyfin.Server.Implementations (Level 7)
                → Emby.Server.Implementations (Level 9)
                  → Jellyfin.Server (Level 10)
                    → Jellyfin.Server.Integration.Tests (Level 11)
                      → Jellyfin.Server.Implementations.Tests (Level 12)
```

**Length**: 13 projects (12 upgrade steps, excluding CodeAnalysis)

**Implications:**
- Any failure in early tiers blocks all downstream projects
- Database layer (Tiers 2-6) is critical foundation
- Server implementation consolidates most dependencies (Tier 10)
- Test projects enable validation at each tier

### Circular Dependencies

**Status**: ✅ **None detected**

The dependency graph is a **Directed Acyclic Graph (DAG)**, enabling clean bottom-up migration.

### Key Dependency Relationships

#### High-Fan-Out Projects (Used by Many)
1. **MediaBrowser.Model** (Level 3): Used by 21 projects
   - Central model definitions
   - Must be stable before progressing
2. **MediaBrowser.Controller** (Level 6): Used by 12 projects
   - Core controller abstractions
   - Critical stabilization point
3. **MediaBrowser.Common** (Level 4): Used by 10 projects
   - Common utilities
   - Early tier with wide impact

#### High-Fan-In Projects (Depend on Many)
1. **Jellyfin.Server** (Level 10): Depends on 9 direct projects
   - Main application entry point
   - Consolidates all functionality
2. **Emby.Server.Implementations** (Level 9): Depends on 14 direct projects
   - Server implementation layer
   - Complex integration point
3. **Jellyfin.Server.Implementations** (Level 7): Depends on 6 direct projects
   - Server infrastructure
   - Database and core implementation

### Between-Tier Dependencies

Each tier depends **only** on lower tiers (strict bottom-up):

- **Tier 2** → Tier 1 (CodeAnalysis only)
- **Tier 3** → Tiers 1-2
- **Tier 4** → Tiers 1-3
- **Tier 5** → Tiers 1-4
- **Tier 6** → Tiers 1-5
- **Tier 7** → Tiers 1-6
- **Tier 8** → Tiers 1-7
- **Tier 9** → Tiers 1-8
- **Tier 10** → Tiers 1-9
- **Tier 11** → Tiers 1-10
- **Tier 12** → Tiers 1-11
- **Tier 13** → Tiers 1-12

**No cross-tier or reverse dependencies** ensure clean migration flow.

## Project-by-Project Plans

### Overview

This section provides detailed migration plans for each project, organized by tier. Each project includes:
- Current and target state
- Migration steps
- Package updates
- Expected breaking changes
- Code modifications
- Testing strategy
- Validation checklist

---

### Tier 1: Foundation Analyzer (NO MIGRATION)

#### Jellyfin.CodeAnalysis
**Current State**: netstandard2.0 (Roslyn analyzer)
**Target State**: netstandard2.0 (UNCHANGED)
**Migration**: None required - remains on netstandard2.0 for broad compatibility

---

### Tier 2: Core Infrastructure

#### Overview
**Projects**: 3  
**Complexity**: Medium  
**Risk**: High (first preview framework exposure)  
**Effort**: Medium  

This tier establishes the foundation infrastructure: database implementations, extension utilities, and media encoding keyframe support. As the first tier to migrate, it serves as the **early warning system** for .NET 11.0 preview issues.

---

#### Jellyfin.Database.Implementations

**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: 6 projects (Data layer, database providers, server implementations)
- **Packages**: Microsoft.EntityFrameworkCore 11.0.0-preview.1 (already upgraded)
- **Risk Level**: High (foundation for all data access)

**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required (already on .NET 11.0-compatible versions)

**Migration Steps**:

1. **Prerequisites**
   - ✅ Jellyfin.CodeAnalysis remains unchanged (netstandard2.0)
   - ✅ .NET 11.0 SDK installed and verified
   - ✅ Backup current solution state

2. **Framework Update**
   - Update `Jellyfin.Database.Implementations.csproj`:
     ```xml
     <TargetFramework>net11.0</TargetFramework>
     ```
   - No other project file changes needed

3. **Package Updates**
   - **All packages already compatible** - no updates required:
     - Microsoft.EntityFrameworkCore: 11.0.0-preview.1 ✅
     - Microsoft.EntityFrameworkCore.Relational: 11.0.0-preview.1 ✅
     - Microsoft.EntityFrameworkCore.Design: 11.0.0-preview.1 ✅

4. **Expected Breaking Changes**
   - ✅ **None identified** by assessment
   - ⚠️ **Monitor for**: EF Core 11.0 preview query translation changes
   - ⚠️ **Monitor for**: Database provider behavior changes

5. **Code Modifications**
   - **Expected**: None required
   - **Potential**: 
     - EF Core API changes (preview-specific)
     - Query translation adjustments
     - Migration compatibility

6. **Testing Strategy**
   - **Build Validation**:
     - Project builds without errors ✅
     - Zero warnings target ✅
     - Code analysis passes ✅

   - **Dependency Validation**:
     - NuGet restore successful ✅
     - No package conflicts ✅

   - **Functional Testing**:
     - Database context initialization ✅
     - Basic CRUD operations (deferred to Tier 6 with providers)

   - **Performance Baseline**:
     - Establish .NET 11.0 build performance metrics
     - Compare against .NET 9.0 baseline

7. **Validation Checklist**
   - [ ] Project file updated to net11.0
   - [ ] Build succeeds without errors
   - [ ] Build succeeds without warnings
   - [ ] NuGet packages restore successfully
   - [ ] No dependency conflicts
   - [ ] Code analysis passes (StyleCop, IDisposableAnalyzers, etc.)
   - [ ] Database context classes compile
   - [ ] No compiler warnings about obsolete APIs
   - [ ] EF Core design-time tools work (if applicable)

---

#### Jellyfin.Extensions

**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: MediaBrowser.Model, Jellyfin.Extensions.Tests
- **Packages**: Minimal (mostly BCL)
- **Risk Level**: Low (simple utility library)

**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required

**Migration Steps**:

1. **Prerequisites**
   - ✅ .NET 11.0 SDK available
   - ✅ No external package dependencies to validate

2. **Framework Update**
   - Update `Jellyfin.Extensions.csproj`:
     ```xml
     <TargetFramework>net11.0</TargetFramework>
     ```

3. **Package Updates**
   - **None required** - uses BCL only

4. **Expected Breaking Changes**
   - ✅ **None expected**
   - Simple extension methods and utilities
   - Minimal BCL surface area

5. **Code Modifications**
   - **Expected**: None
   - **Potential**: None anticipated

6. **Testing Strategy**
   - **Build Validation**:
     - Build without errors/warnings ✅
     - Code analysis passes ✅

   - **Unit Testing**:
     - Deferred to Tier 5 (Jellyfin.Extensions.Tests)

   - **API Compatibility**:
     - Extension methods compile without changes ✅
     - No obsolete API usage ✅

7. **Validation Checklist**
   - [ ] Project file updated to net11.0
   - [ ] Build succeeds without errors
   - [ ] Build succeeds without warnings
   - [ ] No package dependencies to update
   - [ ] Extension methods compile cleanly
   - [ ] Code analysis passes
   - [ ] No breaking changes in BCL APIs used

---

#### Jellyfin.MediaEncoding.Keyframes

**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Hls, test projects
- **Packages**: Minimal
- **Risk Level**: Low (specialized library)

**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required

**Migration Steps**:

1. **Prerequisites**
   - ✅ .NET 11.0 SDK available
   - ✅ Understanding of keyframe extraction functionality

2. **Framework Update**
   - Update `Jellyfin.MediaEncoding.Keyframes.csproj`:
     ```xml
     <TargetFramework>net11.0</TargetFramework>
     ```

3. **Package Updates**
   - **None required** - minimal external dependencies

4. **Expected Breaking Changes**
   - ✅ **None expected**
   - Specialized media encoding logic
   - Limited BCL interaction

5. **Code Modifications**
   - **Expected**: None
   - **Potential**: 
     - I/O API changes (if file operations change)
     - Stream handling adjustments (unlikely)

6. **Testing Strategy**
   - **Build Validation**:
     - Build without errors/warnings ✅
     - Code analysis passes ✅

   - **Unit Testing**:
     - Deferred to Tier 3 (Jellyfin.MediaEncoding.Keyframes.Tests)

   - **Functional Validation**:
     - Keyframe extraction logic compiles ✅
     - FFmpeg integration interfaces unchanged ✅

7. **Validation Checklist**
   - [ ] Project file updated to net11.0
   - [ ] Build succeeds without errors
   - [ ] Build succeeds without warnings
   - [ ] No external package updates needed
   - [ ] Media encoding logic compiles cleanly
   - [ ] Code analysis passes
   - [ ] FFmpeg integration interfaces compatible

---

### Tier 2: Batch Operations

Since all 3 projects in Tier 2 have similar migration profiles, they can be **upgraded simultaneously**:

#### Batch Update Process

1. **Project File Updates** (Single operation)
   - Update all 3 .csproj files to `<TargetFramework>net11.0</TargetFramework>`
   - Commit: "Upgrade Tier 2 projects to .NET 11.0"

2. **Build Validation** (Parallel)
   - Build all 3 projects
   - Check for errors/warnings
   - Verify code analysis passes

3. **Package Restoration** (Parallel)
   - Restore NuGet packages for all projects
   - Verify no conflicts

4. **Integration Check**
   - Build solution to ensure Tier 2 projects compile together
   - Verify dependent projects (still on .NET 9.0) can still reference Tier 2

---

### Tier 2: Completion Criteria

Before proceeding to Tier 3, **all** of the following must be met:

1. ✅ **Build Success**
   - All 3 projects build without errors
   - All 3 projects build without warnings (zero-warning target)

2. ✅ **Package Health**
   - All packages restored successfully
   - No package dependency conflicts
   - EF Core design-time tools functional (Database.Implementations)
 
3. ✅ **Code Quality**
   - Code analysis passes (StyleCop, analyzers)
   - No compiler warnings about obsolete APIs
   - No new code analysis violations introduced

4. ✅ **Preview Framework Assessment**
   - .NET 11.0 SDK functional
   - No blocking preview framework issues discovered
   - Build performance acceptable

5. ✅ **Documentation**
   - Any issues encountered documented
   - Workarounds noted (if applicable)
   - Lessons learned recorded for later tiers

**Decision Point**: If Tier 2 shows critical .NET 11.0 preview issues, **PAUSE** migration and assess viability.

---

### Tier 2: Package Update Reference

| Package | Current | Target | Notes |
|---------|---------|--------|-------|
| Microsoft.EntityFrameworkCore | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |
| Microsoft.EntityFrameworkCore.Relational | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |
| Microsoft.EntityFrameworkCore.Design | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |

**All packages already at .NET 11.0-compatible versions - no package updates required for Tier 2.**

---

### Tier 3: Data Layer

#### Overview
**Projects**: 2  
**Complexity**: Low  
**Risk**: Low  
**Effort**: Low  

Data models and first test validation point. Straightforward migration with immediate test feedback.

---

#### Jellyfin.Data

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis  
**Risk**: Low (data models)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required (all compatible)
3. Build and validate data model classes compile cleanly

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Data entity classes compile
- [ ] EF Core model configuration unchanged
- [ ] Used successfully by MediaBrowser.Model (Tier 4)

---

#### Jellyfin.MediaEncoding.Keyframes.Tests

**Current State**: .NET 9.0 Test Project (xUnit)  
**Target State**: .NET 11.0 Test Project  
**Dependencies**: Jellyfin.MediaEncoding.Keyframes (Tier 2), Jellyfin.CodeAnalysis  
**Risk**: Low (test project)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required:
   - xUnit 2.9.3 ✅
   - xunit.runner.visualstudio 2.8.2 ✅
   - Microsoft.NET.Test.Sdk 18.0.1 ✅
3. Run tests to validate Tier 2 (MediaEncoding.Keyframes)

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] All tests run successfully
- [ ] All tests pass (100% pass rate)
- [ ] Test runner compatible with .NET 11.0
- [ ] Tier 2 keyframes functionality validated

**Tier 3 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.MediaEncoding.Keyframes.Tests: 100% tests pass
3. No package conflicts
4. Tier 2 functionality validated through tests

---

### Tier 4: Model Layer

#### Overview
**Projects**: 1  
**Complexity**: Medium (high fan-out)  
**Risk**: Medium  
**Effort**: Low  

Central model definitions used by 21 projects throughout solution. Critical stability point.

---

#### MediaBrowser.Model

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: Jellyfin.Data (Tier 3), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis  
**Used By**: 21 projects (most of solution)  
**Risk**: Medium (high fan-out = wide impact)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required (compatible packages)
3. Build and validate model classes compile cleanly

**Expected Changes**: None

**Key Focus Areas**:
- DTO models for API serialization
- Query models for filtering/paging
- Configuration models
- Enum definitions

**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] All model classes compile cleanly
- [ ] No JSON serialization API changes
- [ ] Enum definitions unchanged
- [ ] Configuration model binding compatible
- [ ] DTOs serialize/deserialize correctly (tested in Tier 5)

**Special Considerations**:
- **High Fan-Out**: 21 projects depend on this
- **API Surface**: Models used in REST API contracts
- **Serialization**: JSON serialization must remain compatible

**Tier 4 Completion Criteria**:
1. Project builds without errors/warnings
2. All model classes compile without changes
3. No breaking changes in public API surface
4. Ready for validation by Tier 5 tests

---

### Tier 5: Common Utilities & Model Tests

#### Overview
**Projects**: 3  
**Complexity**: Low  
**Risk**: Low  
**Effort**: Low  

Common utilities and validation tests for Tier 4 models. Provides test coverage for central models.

---

#### MediaBrowser.Common

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis  
**Used By**: 10 projects  
**Risk**: Low (utility library)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. Package updates - All compatible:
   - Microsoft.Extensions.DependencyInjection: 11.0.0-preview.1 ✅
   - Microsoft.Extensions.Logging: 11.0.0-preview.1 ✅
   - Microsoft.Extensions.Http: 11.0.0-preview.1 ✅
3. Build and validate common utilities

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Dependency injection helpers compile
- [ ] Logging utilities compatible
- [ ] HTTP client utilities functional
- [ ] Configuration helpers unchanged

---

#### Jellyfin.Extensions.Tests

**Current State**: .NET 9.0 Test Project (xUnit)  
**Target State**: .NET 11.0 Test Project  
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis  
**Risk**: Low (test project)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required (test packages compatible)
3. Run tests to validate Tier 2 extensions

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds
- [ ] All tests run
- [ ] All tests pass (100%)
- [ ] Tier 2 extensions validated

---

#### Jellyfin.Model.Tests

**Current State**: .NET 9.0 Test Project (xUnit)  
**Target State**: .NET 11.0 Test Project  
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis  
**Risk**: Low (test project)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required (test packages compatible)
3. Run tests to validate Tier 4 models

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds
- [ ] All tests run
- [ ] All tests pass (100%)
- [ ] Tier 4 models validated (DTOs, serialization, configuration)

**Tier 5 Completion Criteria**:
1. All 3 projects build without errors/warnings
2. Both test projects: 100% tests pass
3. Tier 2 extensions validated
4. Tier 4 models validated
5. Common utilities functional
6. No package conflicts

---

### Tier 6: Database Providers & Naming ⚠️ CRITICAL TIER

#### Overview
**Projects**: 3  
**Complexity**: High  
**Risk**: CRITICAL  
**Effort**: High  

**This is the most critical tier in the migration.** Database providers are the foundation for all data access throughout Jellyfin. Both PostgreSQL and SQLite EF Core providers are preview versions for .NET 11.0, requiring extensive validation.

**🛑 GO/NO-GO DECISION POINT**: If Tier 6 fails validation, the entire migration may need to pause or revert.

---

#### Emby.Naming

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: MediaBrowser.Model (Tier 4), MediaBrowser.Common (Tier 5), Jellyfin.CodeAnalysis  
**Used By**: MediaBrowser.Controller (Tier 7), Emby.Server.Implementations, Jellyfin.Naming.Tests (Tier 7)  
**Risk**: Low (naming logic)

**Migration Steps**:
1. Update project file: `<TargetFramework>net11.0</TargetFramework>`
2. No package updates required
3. Build and validate naming logic

**Expected Changes**: None

**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Naming pattern logic compiles
- [ ] File/folder naming utilities unchanged
- [ ] Validated by Jellyfin.Naming.Tests (Tier 7)

---

#### Jellyfin.Database.Providers.Postgres ⚠️ CRITICAL

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis  
**Used By**: Jellyfin.Server (Tier 11), Jellyfin.Server.Implementations (Tier 8)  
**Risk**: **CRITICAL** (primary database provider for Jellyfin)

**Package Status**:
- **Npgsql.EntityFrameworkCore.PostgreSQL**: 11.0.0-preview.1 ✅ (already upgraded)
- **Status**: Preview provider for preview framework

**Migration Steps**:

1. **Prerequisites**
   - PostgreSQL database server available for testing
   - Test database with representative Jellyfin schema
   - Baseline performance metrics from .NET 9.0
   - Connection string configuration ready

2. **Framework Update**
   - Update project file: `<TargetFramework>net11.0</TargetFramework>`
   - No package updates required (already on preview)

3. **Expected Breaking Changes**
   - ✅ **None identified** in assessment
   - ⚠️ **Potential**: EF Core 11.0 query translation changes
   - ⚠️ **Potential**: Npgsql provider-specific behavior changes
   - ⚠️ **Potential**: Connection pooling behavior
   - ⚠️ **Potential**: Transaction handling differences

4. **Code Modifications**
   - **Expected**: None
   - **Potential**:
     - DbContext configuration adjustments
     - Connection string format changes
     - Provider-specific query hints
     - Migration compatibility fixes

5. **Testing Strategy** (EXTENSIVE)

   **Build Validation**:
   - [ ] Project builds without errors
   - [ ] Project builds without warnings
   - [ ] Code analysis passes
   - [ ] DbContext registration compiles

   **Database Connection Tests**:
   - [ ] Connection string parsing successful
   - [ ] Database connection established
   - [ ] Connection pooling functional
   - [ ] SSL/TLS connections work (if applicable)
   - [ ] Connection timeouts handled correctly

   **Migration Tests**:
   - [ ] Existing migrations still valid
   - [ ] Can apply migrations to empty database
   - [ ] Can upgrade from previous schema version
   - [ ] Migration history table accessible
   - [ ] No schema drift detected

   **CRUD Operations**:
   - [ ] INSERT operations successful
   - [ ] SELECT queries return correct data
   - [ ] UPDATE operations modify records
   - [ ] DELETE operations remove records
   - [ ] Bulk operations functional
   - [ ] Concurrent operations safe

   **Query Translation**:
   - [ ] LINQ queries translate to SQL correctly
   - [ ] Complex queries (joins, aggregations) work
   - [ ] Navigation properties load correctly
   - [ ] Explicit loading functional
   - [ ] Eager loading (Include) functional
   - [ ] Lazy loading compatible (if enabled)

   **Transaction Tests**:
   - [ ] Explicit transactions work
   - [ ] Rollback functional
   - [ ] Nested transactions (if used)
   - [ ] Distributed transactions (if used)
   - [ ] Transaction isolation levels correct

   **Performance Tests**:
   - [ ] Query performance comparable to .NET 9.0 baseline
   - [ ] Insert/update performance acceptable
   - [ ] Bulk operation performance
   - [ ] Connection pool performance
   - [ ] No memory leaks detected
   - [ ] No excessive allocations

   **Concurrency Tests**:
   - [ ] Concurrent reads safe
   - [ ] Concurrent writes safe
   - [ ] Optimistic concurrency functional
   - [ ] Pessimistic locking works (if used)
   - [ ] Deadlock handling correct

   **Edge Cases**:
   - [ ] NULL value handling
   - [ ] Large result sets
   - [ ] Long-running queries
   - [ ] Connection drops handled
   - [ ] Database restart recovery

6. **Validation Checklist**
   - [ ] All connection tests pass
   - [ ] All migration tests pass
   - [ ] All CRUD tests pass
   - [ ] All query translation tests pass
   - [ ] All transaction tests pass
   - [ ] Performance within acceptable range (<10% regression)
   - [ ] Concurrency tests pass
   - [ ] Edge case tests pass
   - [ ] No critical issues detected

7. **Performance Baseline Comparison**
   - Document query performance vs. .NET 9.0
   - Compare connection pool behavior
   - Measure memory usage
   - Track any regressions

**Contingency Plans**:
- **If connection issues**: Check Npgsql preview release notes; report bug upstream
- **If query translation fails**: Rewrite queries or wait for provider fix
- **If performance degrades >20%**: Profile and optimize or consider blocking issue
- **If critical bugs**: May need to pause migration until Npgsql fix available

---

#### Jellyfin.Database.Providers.Sqlite ⚠️ CRITICAL

**Current State**: .NET 9.0 Class Library  
**Target State**: .NET 11.0 Class Library  
**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis  
**Used By**: Jellyfin.Server (Tier 11)  
**Risk**: **CRITICAL** (alternative database provider for Jellyfin)

**Package Status**:
- **Microsoft.EntityFrameworkCore.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded)
- **Microsoft.Data.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded)
- **Status**: Preview provider for preview framework

**Migration Steps**:

1. **Prerequisites**
   - SQLite database file available for testing
   - Test database with representative Jellyfin schema
   - Baseline performance metrics from .NET 9.0
   - Write permissions verified

2. **Framework Update**
   - Update project file: `<TargetFramework>net11.0</TargetFramework>`
   - No package updates required (already on preview)

3. **Expected Breaking Changes**
   - ✅ **None identified** in assessment
   - ⚠️ **Potential**: EF Core 11.0 query translation changes
   - ⚠️ **Potential**: SQLite provider-specific behavior changes
   - ⚠️ **Potential**: File locking behavior
   - ⚠️ **Potential**: WAL mode changes

4. **Code Modifications**
   - **Expected**: None
   - **Potential**:
     - DbContext configuration adjustments
     - Connection string format changes
     - Pragmas or SQLite-specific settings
     - Migration compatibility fixes

5. **Testing Strategy** (EXTENSIVE)

   **Build Validation**:
   - [ ] Project builds without errors
   - [ ] Project builds without warnings
   - [ ] Code analysis passes
   - [ ] DbContext registration compiles

   **Database File Tests**:
   - [ ] Database file created successfully
   - [ ] Database file opened correctly
   - [ ] File locking works correctly
   - [ ] WAL mode functional (if used)
   - [ ] File permissions respected
   - [ ] Backup/restore operations work

   **Migration Tests**:
   - [ ] Existing migrations still valid
   - [ ] Can apply migrations to empty database
   - [ ] Can upgrade from previous schema version
   - [ ] Migration history table accessible
   - [ ] No schema drift detected

   **CRUD Operations**:
   - [ ] INSERT operations successful
   - [ ] SELECT queries return correct data
   - [ ] UPDATE operations modify records
   - [ ] DELETE operations remove records
   - [ ] Bulk operations functional
   - [ ] Concurrent operations safe

   **Query Translation**:
   - [ ] LINQ queries translate to SQL correctly
   - [ ] Complex queries (joins, aggregations) work
   - [ ] Navigation properties load correctly
   - [ ] Explicit loading functional
   - [ ] Eager loading (Include) functional
   - [ ] SQLite-specific SQL features work

   **Transaction Tests**:
   - [ ] Explicit transactions work
   - [ ] Rollback functional
   - [ ] Nested transactions (if used)
   - [ ] Transaction isolation correct

   **Performance Tests**:
   - [ ] Query performance comparable to .NET 9.0 baseline
   - [ ] Insert/update performance acceptable
   - [ ] Bulk operation performance
   - [ ] File I/O performance
   - [ ] No memory leaks detected
   - [ ] Database size remains reasonable

   **Concurrency Tests**:
   - [ ] Concurrent reads safe
   - [ ] Concurrent writes safe (within SQLite limits)
   - [ ] File locking prevents corruption
   - [ ] Busy timeout handling works

   **Edge Cases**:
   - [ ] NULL value handling
   - [ ] Large result sets
   - [ ] Long-running queries
   - [ ] Database corruption recovery (if applicable)
   - [ ] Disk full scenarios handled

6. **Validation Checklist**
   - [ ] All file operation tests pass
   - [ ] All migration tests pass
   - [ ] All CRUD tests pass
   - [ ] All query translation tests pass
   - [ ] All transaction tests pass
   - [ ] Performance within acceptable range (<10% regression)
   - [ ] Concurrency tests pass
   - [ ] Edge case tests pass
   - [ ] No critical issues detected

7. **Performance Baseline Comparison**
   - Document query performance vs. .NET 9.0
   - Compare file I/O behavior
   - Measure database file size
   - Track any regressions

**Contingency Plans**:
- **If file locking issues**: Check Microsoft.Data.Sqlite preview release notes
- **If query translation fails**: Rewrite queries or wait for provider fix
- **If performance degrades >20%**: Profile and optimize or consider blocking issue
- **If critical bugs**: May need to pause migration until EF Core Sqlite fix available

---

### Tier 6: Integration Testing

After all 3 projects migrate, perform **cross-provider validation**:

#### Database Provider Integration Tests

1. **Dual-Provider Tests**
   - [ ] Can switch between PostgreSQL and SQLite configurations
   - [ ] Same queries work on both providers
   - [ ] Schema migrations compatible across providers
   - [ ] Data integrity maintained across providers

2. **Real-World Scenario Tests**
   - [ ] User authentication/authorization queries
   - [ ] Media library metadata queries
   - [ ] Playback session tracking
   - [ ] User preferences and settings
   - [ ] Search and filtering operations

3. **Load Testing**
   - [ ] Concurrent user simulations
   - [ ] Large library operations (10k+ items)
   - [ ] Sustained query load
   - [ ] Memory usage under load

4. **Failure Recovery**
   - [ ] Database connection drop recovery
   - [ ] Transaction rollback on errors
   - [ ] Database restart handling
   - [ ] Corrupted data detection

---

### Tier 6: Completion Criteria (STRICT)

🛑 **This tier has the STRICTEST completion criteria.** Do not proceed to Tier 7 unless ALL criteria met:

1. ✅ **Build Success**
   - All 3 projects build without errors
   - All 3 projects build without warnings

2. ✅ **Database Connection**
   - PostgreSQL provider connects successfully
   - SQLite provider connects successfully
   - Connection pooling functional for both

3. ✅ **Migration Compatibility**
   - All existing migrations apply successfully
   - No schema drift detected
   - Migration history intact

4. ✅ **CRUD Operations**
   - All CRUD tests pass (100%) for both providers
   - Concurrency tests pass
   - Transaction tests pass

5. ✅ **Query Translation**
   - LINQ queries translate correctly
   - Complex queries work
   - Navigation loading functional

6. ✅ **Performance Acceptable**
   - Query performance: <10% regression vs. .NET 9.0
   - Connection performance: Comparable to baseline
   - Memory usage: No significant increase
   - No memory leaks detected

7. ✅ **Integration Tests**
   - Dual-provider tests pass
   - Real-world scenario tests pass
   - Load tests pass (within acceptable limits)
   - Failure recovery tests pass

8. ✅ **Manual Validation**
   - Senior engineer review of provider behavior
   - Database administrator verification (for PostgreSQL)
   - Sign-off on performance metrics

9. ✅ **Documentation**
   - All issues encountered documented
   - Performance baselines recorded
   - Known limitations documented
   - Contingency plans ready

**🛑 DECISION POINT**: If **any** critical issues detected in Tier 6, **PAUSE** migration:
- **Option A**: Report issues to Npgsql/EF Core teams; wait for fixes
- **Option B**: Implement workarounds (if feasible)
- **Option C**: Revert migration; target .NET 10.0 LTS instead
- **Option D**: Continue with documented risks (ONLY if non-critical)

**Tier 6 is the primary risk gate. Proceed to Tier 7 only with high confidence in database provider stability.**

---

### Tier 7: Controller Layer

#### Overview
**Projects**: 2 (Jellyfin.Naming.Tests, MediaBrowser.Controller)  
**Complexity**: Medium  
**Risk**: Medium  
**Effort**: Medium  

Controller abstractions and naming validation. MediaBrowser.Controller has high fan-out (12 projects depend on it).

#### Quick Migration Profile

**Both Projects**:
- Update to `<TargetFramework>net11.0</TargetFramework>`
- No package updates required (all compatible)
- Build and run tests

**MediaBrowser.Controller**:
- **Risk**: Medium (high fan-out)
- **Dependencies**: Tiers 2-6
- **Used By**: 12 projects (business logic tier)
- **Focus**: Controller abstractions, interfaces for repositories/services
- **Validation**: Jellyfin.Controller.Tests (Tier 8)

**Jellyfin.Naming.Tests**:
- **Risk**: Low (test project)
- **Validates**: Emby.Naming (Tier 6)
- **Expected**: 100% tests pass

**Tier 7 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.Naming.Tests: 100% pass rate
3. MediaBrowser.Controller public API unchanged
4. Ready for Tier 8 business logic

---

### Tier 8: Business Logic ⚡ LARGEST TIER

#### Overview
**Projects**: 12 (largest tier)  
**Complexity**: High  
**Risk**: High  
**Effort**: High  

This tier contains most of Jellyfin's business logic: media processing, networking, providers, drawing, and server infrastructure. **High parallelization potential** within tier.

#### Project Grouping for Parallel Execution

**Group A: Media Processing (3 projects)**
- Emby.Photos
- MediaBrowser.MediaEncoding
- Jellyfin.MediaEncoding.Hls

**Group B: Drawing & Graphics (2 projects)**
- Jellyfin.Drawing
- Jellyfin.Drawing.Skia

**Group C: Business Services (4 projects)**
- Jellyfin.LiveTv
- Jellyfin.Networking
- MediaBrowser.Providers
- MediaBrowser.XbmcMetadata

**Group D: Metadata & Server Infrastructure (3 projects)**
- MediaBrowser.LocalMetadata
- Jellyfin.Server.Implementations
- Jellyfin.Controller.Tests

---

#### Group A: Media Processing

##### Emby.Photos
- **Risk**: Medium (image processing)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Photo library management
- **Validation**: Build + integration tests

##### MediaBrowser.MediaEncoding
- **Risk**: High (FFmpeg integration)
- **Packages**: No updates needed
- **Focus**: Video/audio transcoding, FFmpeg process management
- **Key Tests**:
  - [ ] FFmpeg process spawning works
  - [ ] Stream handling functional
  - [ ] Transcoding profiles correct
  - [ ] Process cleanup on abort

##### Jellyfin.MediaEncoding.Hls
- **Risk**: Medium (HLS streaming)
- **Dependencies**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Keyframes
- **Focus**: HLS playlist generation, segmentation
- **Key Tests**:
  - [ ] Manifest generation correct
  - [ ] Segment timing accurate
  - [ ] Playlist updates work

---

#### Group B: Drawing & Graphics

##### Jellyfin.Drawing
- **Risk**: Medium (graphics operations)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Image operations, thumbnail generation
- **Key Tests**:
  - [ ] Image loading/saving works
  - [ ] Thumbnail generation functional
  - [ ] Image format conversions

##### Jellyfin.Drawing.Skia
- **Risk**: High (native library interop)
- **Packages**: 
  - SkiaSharp 3.116.1 ✅
  - SkiaSharp.HarfBuzz 3.116.1 ✅
  - SkiaSharp.NativeAssets.Linux 3.116.1 ✅
  - HarfBuzzSharp.NativeAssets.Linux 8.3.1.1 ✅
- **Focus**: SkiaSharp-based image processing
- **Critical Tests**:
  - [ ] SkiaSharp native libraries load
  - [ ] Image processing operations work
  - [ ] Font rendering functional
  - [ ] Cross-platform compatibility (Linux primary)
  - [ ] No memory leaks in native interop
- **Contingency**: If SkiaSharp issues, check for .NET 11.0-specific native library versions

---

#### Group C: Business Services

##### Jellyfin.LiveTv
- **Risk**: Medium (Live TV functionality)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Live TV guide, recording management
- **Tests**: Jellyfin.LiveTv.Tests (Tier 9)

##### Jellyfin.Networking
- **Risk**: Medium (network operations)
- **Dependencies**: MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Network discovery, DLNA, SSDP
- **Key Tests**:
  - [ ] Network interface detection
  - [ ] DLNA device discovery
  - [ ] Socket operations
  - [ ] UDP/TCP communication
- **Tests**: Jellyfin.Networking.Tests (Tier 9)

##### MediaBrowser.Providers
- **Risk**: Medium (metadata providers)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Metadata fetching from external sources (TMDb, MusicBrainz, etc.)
- **Packages**:
  - TMDbLib 2.3.0 ✅
  - MetaBrainz.MusicBrainz 8.0.1 ✅
- **Tests**: Jellyfin.Providers.Tests (Tier 9)

##### MediaBrowser.XbmcMetadata
- **Risk**: Low (metadata parsing)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: NFO file parsing/writing
- **Tests**: Jellyfin.XbmcMetadata.Tests (Tier 9)

---

#### Group D: Metadata & Server Infrastructure

##### MediaBrowser.LocalMetadata
- **Risk**: Low (local metadata)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Local metadata file operations

##### Jellyfin.Server.Implementations
- **Risk**: High (server infrastructure)
- **Dependencies**: 6 direct dependencies (Jellyfin.Database.Providers.Postgres, Jellyfin.Data, MediaBrowser.Model, MediaBrowser.Controller, Jellyfin.Database.Implementations)
- **Focus**: Server core implementations, dependency injection, configuration
- **Key Areas**:
  - Database integration (uses Tier 6 providers)
  - Configuration management
  - Service registration
  - Plugin infrastructure
- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13)

##### Jellyfin.Controller.Tests
- **Risk**: Low (test project)
- **Validates**: MediaBrowser.Controller (Tier 7)
- **Expected**: 100% tests pass

---

### Tier 8: Batch Migration Strategy

Due to 12 projects, **use phased approach within tier**:

#### Phase 8A: Update All Project Files (Single Commit)
- Update all 12 .csproj files to `<TargetFramework>net11.0</TargetFramework>`
- Commit: "Upgrade Tier 8 projects to .NET 11.0"

#### Phase 8B: Build Validation (Parallel by Group)
- Build Group A (Media Processing)
- Build Group B (Drawing & Graphics)
- Build Group C (Business Services)
- Build Group D (Metadata & Infrastructure)
- Fix any compilation errors

#### Phase 8C: Integration Testing
- Run Jellyfin.Controller.Tests (validates Tier 7)
- Integration test between groups
- Validate SkiaSharp native libraries (Group B)
- Validate FFmpeg integration (Group A)
- Validate networking operations (Group C)

---

### Tier 8: Completion Criteria

1. ✅ **Build Success**
   - All 12 projects build without errors
   - All 12 projects build without warnings

2. ✅ **Package Health**
   - All packages restored
   - No conflicts
   - SkiaSharp native libraries load successfully

3. ✅ **Group Validation**
   - **Group A**: FFmpeg operations functional; HLS generation works
   - **Group B**: SkiaSharp operations successful; image processing works
   - **Group C**: Network operations functional; metadata providers work
   - **Group D**: Server infrastructure compiles; controller tests pass

4. ✅ **Critical Tests**
   - Jellyfin.Controller.Tests: 100% pass
   - Native library interop validated (SkiaSharp)
   - Process management validated (FFmpeg)
   - Network operations validated

5. ✅ **Performance**
   - Image processing: Comparable to .NET 9.0
   - Transcoding: No significant regression
   - Network operations: Acceptable latency

**Tier 8 represents majority of application functionality. Thorough validation required before proceeding.**

---

### Tier 9: API & Tests

#### Overview
**Projects**: 8 (Jellyfin.Api + 7 test projects)  
**Complexity**: Medium  
**Risk**: Medium  
**Effort**: Medium  

API layer and comprehensive test coverage for Tier 8 business logic.

#### Projects

**Jellyfin.Api** (ASP.NET Core API):
- **Risk**: High (REST API)
- **Dependencies**: Jellyfin.Networking, Jellyfin.MediaEncoding.Hls, MediaBrowser.MediaEncoding, MediaBrowser.Controller
- **Packages**:
  - Microsoft.AspNetCore.Authorization: 11.0.0-preview.1 ✅
  - Swashbuckle.AspNetCore: 7.3.2 ✅
  - Swashbuckle.AspNetCore.ReDoc: 6.9.0 ✅
- **Key Areas**:
  - REST API controllers
  - Authentication/authorization
  - API versioning
  - OpenAPI/Swagger
- **Tests**: Jellyfin.Api.Tests (Tier 10)

**Test Projects** (7 projects):
- Jellyfin.Common.Tests
- Jellyfin.LiveTv.Tests
- Jellyfin.MediaEncoding.Hls.Tests
- Jellyfin.MediaEncoding.Tests
- Jellyfin.Networking.Tests
- Jellyfin.Providers.Tests
- Jellyfin.XbmcMetadata.Tests

**Migration Strategy**:
1. Update all 8 project files to net11.0
2. Build API project; fix any ASP.NET Core compatibility issues
3. Run all 7 test projects (validates Tier 8)

**Tier 9 Completion Criteria**:
1. Jellyfin.Api builds without errors/warnings
2. API controllers compile; routing works
3. Authentication/authorization unchanged
4. Swagger/OpenAPI generation works
5. **All 7 test projects: 100% pass rate**
6. Tier 8 business logic validated through tests

---

### Tier 10: Server Implementation

#### Overview
**Projects**: 2  
**Complexity**: High  
**Risk**: High  
**Effort**: High  

Server implementations that integrate all lower tiers.

#### Emby.Server.Implementations
- **Risk**: High (integration complexity)
- **Dependencies**: 14 direct dependencies (most of solution)
- **Focus**: Server implementation layer integrating all features
- **Migration**: Update to net11.0; validate integration
- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13)

#### Jellyfin.Api.Tests
- **Risk**: Low (test project)
- **Validates**: Jellyfin.Api (Tier 9)
- **Expected**: 100% tests pass

**Tier 10 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.Api.Tests: 100% pass
3. Server implementations compile and integrate all dependencies
4. No integration conflicts

---

### Tier 11: Main Application

#### Overview
**Projects**: 1 (Jellyfin.Server)  
**Complexity**: High  
**Risk**: High  
**Effort**: Medium  

Main application entry point - consolidates all functionality.

#### Jellyfin.Server
- **Risk**: High (application entry point)
- **Dependencies**: 9 direct dependencies
- **Type**: ASP.NET Core application
- **Packages**:
  - Serilog.AspNetCore: 10.0.0 ✅
  - prometheus-net.AspNetCore: 8.2.1 ✅
  - Microsoft.AspNetCore.Mvc.Testing: 11.0.0-preview.1 ✅
- **Key Areas**:
  - Application startup (Program.cs, Startup.cs)
  - ASP.NET Core hosting
  - Middleware pipeline
  - Dependency injection configuration
  - Logging configuration (Serilog)
  - Metrics (Prometheus)

**Migration Steps**:
1. Update to net11.0
2. Validate startup configuration
3. Test application starts
4. Validate middleware pipeline
5. Check dependency injection registration
6. Verify logging/metrics

**Critical Tests**:
- [ ] Application starts successfully
- [ ] No startup exceptions
- [ ] All services registered correctly
- [ ] Middleware pipeline intact
- [ ] API responds to requests
- [ ] Health checks pass
- [ ] Metrics collected
- [ ] Logging functional

**Tier 11 Completion Criteria**:
1. Project builds without errors/warnings
2. Application starts successfully
3. Basic HTTP requests work (200 OK)
4. Health checks pass
5. No startup errors in logs
6. Ready for integration testing

---

### Tier 12: Integration Tests

#### Overview
**Projects**: 2  
**Complexity**: Medium  
**Risk**: Medium  
**Effort**: Medium  

End-to-end integration testing of full application stack.

#### Jellyfin.Server.Integration.Tests
- **Risk**: Medium (integration tests)
- **Dependencies**: Jellyfin.Server (Tier 11)
- **Focus**: End-to-end API testing, authentication flows, feature integration

#### Jellyfin.Server.Tests
- **Risk**: Medium (application tests)
- **Dependencies**: Jellyfin.Server (Tier 11)
- **Focus**: Server startup, configuration, basic functionality

**Migration**: Update both to net11.0; run full test suite

**Tier 12 Completion Criteria**:
1. Both test projects build
2. Jellyfin.Server.Tests: 100% pass
3. Jellyfin.Server.Integration.Tests: 100% pass
4. All integration scenarios validated
5. Authentication/authorization flows work
6. API endpoints functional

---

### Tier 13: Final Test Validation

#### Overview
**Projects**: 1  
**Complexity**: Low  
**Risk**: Low  
**Effort**: Low  

Final validation of server implementations with integration context.

#### Jellyfin.Server.Implementations.Tests
- **Risk**: Low (final test validation)
- **Dependencies**: Tier 12 (integration tests), Emby.Server.Implementations, Jellyfin.Server.Implementations
- **Focus**: Server implementation validation

**Migration**: Update to net11.0; run tests

**Tier 13 Completion Criteria**:
1. Project builds
2. 100% tests pass
3. All server implementations validated
4. No regressions detected

---

## Testing & Validation Strategy

### Multi-Level Testing Approach

The migration employs testing at every tier to ensure stability before proceeding.

#### Per-Tier Testing

**Build-Time Validation** (Every Tier):
- Zero compilation errors
- Zero warnings (target)
- Code analysis passes
- Package restoration successful

**Unit Testing** (Tiers with Test Projects):
- 100% test pass rate required
- No skipped tests
- No degraded performance
- Tests validate lower tiers

**Integration Testing** (Critical Tiers):
- Tier 6: Database provider integration tests
- Tier 9: API integration tests
- Tier 12: Full application integration tests

#### Phase-by-Phase Testing Requirements

| Phase | Test Requirements | Success Criteria |
|-------|-------------------|------------------|
| **Phase 1** (Tier 2) | Build validation; no unit tests yet | Builds clean; preview framework functional |
| **Phase 2** (Tier 3) | Jellyfin.MediaEncoding.Keyframes.Tests | 100% pass; Tier 2 validated |
| **Phase 3** (Tier 4) | Build only; tested in Phase 4 | Builds clean |
| **Phase 4** (Tier 5) | Jellyfin.Extensions.Tests + Jellyfin.Model.Tests | 100% pass; Tiers 2 & 4 validated |
| **Phase 5** (Tier 6) | **CRITICAL: Extensive database tests** | All database integration tests pass |
| **Phase 6** (Tier 7) | Jellyfin.Naming.Tests | 100% pass; Tier 6 validated |
| **Phase 7** (Tier 8) | Jellyfin.Controller.Tests | 100% pass; Tier 7 validated |
| **Phase 8** (Tier 9) | 7 test projects | 100% pass all; Tier 8 validated |
| **Phase 9** (Tier 10) | Jellyfin.Api.Tests | 100% pass; API validated |
| **Phase 10** (Tier 11) | Manual smoke tests | Application starts; basic features work |
| **Phase 11** (Tier 12) | Integration + Server tests | 100% pass; full stack validated |
| **Phase 12** (Tier 13) | Jellyfin.Server.Implementations.Tests | 100% pass; server validated |
| **Phase 13** (All) | **Full solution validation** | All tests pass; smoke tests pass; performance acceptable |

### Manual Testing Requirements

#### Tier 11 Smoke Tests (Critical)
After Jellyfin.Server migrates, perform manual validation:

1. **Application Startup**
   - [ ] Server starts without errors
   - [ ] No exceptions in startup logs
   - [ ] Health checks respond

2. **Basic Features**
   - [ ] Web UI loads
   - [ ] User authentication works
   - [ ] Library browsing functional
   - [ ] Media playback initiates

3. **API Validation**
   - [ ] REST API responds
   - [ ] Authentication endpoints work
   - [ ] Basic CRUD operations successful

4. **Database Operations**
   - [ ] Database queries work (PostgreSQL or SQLite)
   - [ ] No connection errors
   - [ ] CRUD operations persist

### Performance Testing

**Baseline Comparison Points**:
- Tier 6: Database query performance
- Tier 8: Image processing, transcoding performance
- Tier 11: Application startup time, API response time

**Acceptable Performance**:
- Query performance: <10% regression
- Image/video processing: <15% regression
- Startup time: <20% regression
- Memory usage: <15% increase

**Performance Degradation Response**:
- Document regression
- Profile with dotnet-trace/PerfView
- Report to .NET team if framework-related
- Consider optimization or pause if severe (>30% regression)

### Comprehensive Validation (Phase 13)

After Tier 13 complete, perform full solution validation:

#### Build Validation
- [ ] Full solution builds without errors
- [ ] Full solution builds without warnings
- [ ] All projects target net11.0 (except CodeAnalysis)
- [ ] No package conflicts across solution

#### Test Suite Validation
- [ ] All 15 test projects run successfully
- [ ] 100% test pass rate across solution
- [ ] No flaky tests
- [ ] Test execution time acceptable

#### Smoke Testing
- [ ] Application starts and runs
- [ ] All major features functional:
  - User authentication
  - Library management
  - Media playback
  - Transcoding
  - Live TV (if applicable)
  - Metadata fetching
  - Image processing
  - Network discovery
- [ ] No critical errors in logs
- [ ] Health checks pass

#### Performance Validation
- [ ] Startup time within acceptable range
- [ ] API response times acceptable
- [ ] Database query performance good
- [ ] Transcoding performance acceptable
- [ ] Memory usage reasonable
- [ ] No memory leaks detected

#### Deployment Testing
- [ ] Application deploys successfully
- [ ] Runs on target platforms (Linux, Windows, Docker)
- [ ] Configuration migration works
- [ ] Database migrations successful
- [ ] Existing data accessible

#### Rollback Validation
- [ ] Can revert to previous .NET version if needed
- [ ] Backup/restore procedures work
- [ ] Database rollback possible (if needed)

## Risk Management

### High-Level Risk Assessment

The migration to .NET 11.0 (PREVIEW) presents **moderate to high risk** despite clean compatibility analysis:

#### Risk Categories

| Risk Level | Description | Count | Projects/Areas |
|------------|-------------|-------|----------------|
| **CRITICAL** | Preview framework; database providers | 2 | .NET 11.0 PREVIEW stability; PostgreSQL/SQLite EF providers |
| **HIGH** | Large complex projects; media processing | 5 | Jellyfin.Server, Emby.Server.Implementations, MediaBrowser.MediaEncoding, SkiaSharp, HLS encoding |
| **MEDIUM** | ASP.NET Core application; multiple dependencies | 8 | Jellyfin.Api, Jellyfin.Server.Implementations, MediaBrowser.Controller, networking, providers |
| **LOW** | Small libraries; test projects | 25 | Extensions, models, most test projects |

### Critical Risks

#### 1. Preview Framework Instability (.NET 11.0 PREVIEW)

**Risk**: CRITICAL  
**Impact**: Entire solution  
**Probability**: HIGH  

**Description**:
.NET 11.0 is in preview - not production-ready. May exhibit:
- Runtime instability
- Unexpected breaking changes in preview builds
- Performance regressions
- Undocumented API changes
- Preview build tooling issues
- Missing or incomplete features

**Mitigation**:
- ✅ Bottom-up approach exposes issues early (Tier 2 discovery)
- ✅ Extensive testing at each tier before proceeding
- ✅ Monitor .NET 11.0 preview release notes for known issues
- ✅ Maintain ability to rollback to .NET 9.0 or switch to .NET 10.0 LTS
- ✅ Test on target deployment environments early
- ✅ Consider pausing if critical preview bugs discovered

**Contingency**:
- If critical preview issues: revert and target .NET 10.0 LTS instead
- If minor issues: document and work around, monitor for preview fixes
- If blocking issues in Tier 2-4: pause migration until preview stabilizes

#### 2. Database Provider Compatibility (Tier 6)

**Risk**: CRITICAL  
**Impact**: All database operations (entire application)  
**Probability**: MEDIUM  

**Description**:
Database providers are critical infrastructure:
- **Npgsql.EntityFrameworkCore.PostgreSQL 11.0.0-preview.1**: Preview provider for preview framework
- **Microsoft.EntityFrameworkCore.Sqlite 11.0.0-preview.1**: Preview EF Core provider
- Jellyfin.Database.Implementations integrates both providers
- Any provider issue breaks data access throughout application

**Mitigation**:
- ✅ Tier 6 dedicated phase for database provider validation
- ✅ Extensive integration testing with real databases (PostgreSQL, SQLite)
- ✅ Test migration scenarios, CRUD operations, query performance
- ✅ Validate connection pooling, transaction behavior
- ✅ Performance benchmarking vs. .NET 9.0 baseline
- ✅ Test under load/concurrent operations

**Contingency**:
- If provider issues: report to Npgsql/EF Core teams, monitor for fixes
- If blocking: consider staying on .NET 9.0 until stable provider releases
- If PostgreSQL issues only: validate SQLite as temporary fallback
- Database provider failures block entire migration at Tier 6

### High Risks

#### 3. Media Processing Libraries (SkiaSharp, Tier 8)

**Risk**: HIGH  
**Impact**: Image processing, thumbnail generation, graphics  
**Probability**: MEDIUM  

**Description**:
- SkiaSharp 3.116.1 used for image processing
- HarfBuzzSharp.NativeAssets.Linux for font rendering
- Native library interop may have .NET 11.0 issues
- Cross-platform compatibility concerns (Linux, Windows, macOS)

**Mitigation**:
- ✅ Test image processing workflows in Tier 8
- ✅ Validate thumbnail generation, image transcoding
- ✅ Test on target platforms (Linux primary for Jellyfin)
- ✅ Verify native library loading and interop
- ✅ Performance testing for image operations

**Contingency**:
- If issues: check for SkiaSharp .NET 11.0 updates
- Report issues to SkiaSharp maintainers
- May need to wait for library updates

#### 4. Main Server Application (Jellyfin.Server, Tier 11)

**Risk**: HIGH  
**Impact**: Application entry point, all features  
**Probability**: LOW  

**Description**:
- Main application consolidates all functionality
- ASP.NET Core 11.0 preview hosting
- Startup configuration, middleware, dependency injection
- All features converge here

**Mitigation**:
- ✅ Tiers 2-10 stable before reaching Tier 11
- ✅ Comprehensive integration testing
- ✅ Manual smoke testing of key user scenarios
- ✅ Performance monitoring vs. baseline
- ✅ Error handling and logging verification

**Contingency**:
- If startup issues: check ASP.NET Core 11.0 preview breaking changes
- Isolate failing features and test independently
- May need ASP.NET Core configuration adjustments

#### 5. Entity Framework Core 11.0 Preview

**Risk**: HIGH  
**Impact**: All data access  
**Probability**: MEDIUM  

**Description**:
- EF Core 11.0.0-preview.1 used throughout solution
- Query translation, migrations, change tracking
- Preview may have query translation issues or performance changes

**Mitigation**:
- ✅ Validate existing database migrations still work
- ✅ Test query patterns used throughout application
- ✅ Monitor query performance
- ✅ Validate LINQ-to-SQL translation
- ✅ Test include/navigation loading

**Contingency**:
- If query translation fails: rewrite queries or wait for EF Core fixes
- Performance issues: profile and optimize or report upstream
- Migration issues: may need manual SQL adjustments

### Medium Risks

#### 6. ASP.NET Core 11.0 API Compatibility (Tier 9)

**Risk**: MEDIUM  
**Impact**: REST API, authentication, authorization  
**Probability**: MEDIUM  

**Description**:
- Jellyfin.Api uses ASP.NET Core 11.0 preview
- Authentication, authorization, middleware pipeline
- API controllers, routing, model binding

**Mitigation**:
- ✅ API tests in Tier 9 validate endpoints
- ✅ Test authentication/authorization flows
- ✅ Validate OpenAPI/Swagger generation
- ✅ Test API versioning

**Contingency**:
- If auth issues: review ASP.NET Core Identity changes
- If routing breaks: adjust route configurations
- API compatibility issues may require code changes

#### 7. Media Encoding & Streaming (Tier 8-9)

**Risk**: MEDIUM  
**Impact**: Video transcoding, HLS streaming  
**Probability**: LOW  

**Description**:
- MediaBrowser.MediaEncoding, Jellyfin.MediaEncoding.Hls
- Video/audio transcoding, HLS playlist generation
- FFmpeg integration (process spawning, stream handling)

**Mitigation**:
- ✅ Test transcoding workflows
- ✅ Validate HLS manifest generation
- ✅ Test FFmpeg process management
- ✅ Performance validation for encoding

**Contingency**:
- If process issues: check .NET 11.0 Process API changes
- If streaming breaks: validate HLS encoding pipeline
- May need FFmpeg command adjustments

#### 8. Networking & Connectivity (Tier 8)

**Risk**: MEDIUM  
**Impact**: Network discovery, DLNA, remote access  
**Probability**: LOW  

**Description**:
- Jellyfin.Networking for network operations
- DLNA, SSDP, network interface detection
- Socket operations, UDP/TCP communication

**Mitigation**:
- ✅ Test network discovery scenarios
- ✅ Validate DLNA device detection
- ✅ Test under various network configurations
- ✅ Socket operation validation

**Contingency**:
- If network issues: check .NET 11.0 networking changes
- May need Socket or HttpClient configuration adjustments
- DLNA issues may require protocol-level debugging

### Low Risks

#### 9. Test Projects

**Risk**: LOW  
**Impact**: Testing infrastructure only  
**Probability**: LOW  

**Description**:
15 test projects throughout tiers; xUnit 2.9.3, Moq 4.18.4

**Mitigation**:
- ✅ Test framework compatibility pre-verified
- ✅ Test projects upgraded incrementally with their targets
- ✅ Validation at each tier

**Contingency**:
- If test framework issues: update xUnit/Moq/AutoFixture
- Test failures indicate actual issues, not test framework problems

#### 10. Small Utility Libraries

**Risk**: LOW  
**Impact**: Limited to specific features  
**Probability**: VERY LOW  

**Description**:
- Extensions, utilities, models (Tiers 2-5)
- Simple, well-tested code
- Minimal external dependencies

**Mitigation**:
- ✅ Unit tests cover functionality
- ✅ Early tiers - failures detected immediately
- ✅ Easy to isolate and fix

**Contingency**:
- Minimal risk; standard debugging if issues arise

### Risk Mitigation Matrix

| Tier | Primary Risks | Mitigation Strategy | Fallback |
|------|---------------|---------------------|----------|
| **Tier 2** | Preview framework first exposure | Extensive testing; early warning system | Revert if critical issues |
| **Tier 3-5** | Model/data layer stability | Unit tests, validation | Isolated fixes |
| **Tier 6** | Database providers (CRITICAL) | Integration tests, performance testing | Block migration if fails |
| **Tier 7** | Controller abstractions | Naming tests, validation | Standard debugging |
| **Tier 8** | Media processing, networking | Functional testing, cross-platform validation | Feature-specific fixes |
| **Tier 9** | API, authentication | API tests, auth flow validation | ASP.NET Core config adjustments |
| **Tier 10-11** | Server implementation, main app | Integration tests, smoke testing | Startup configuration fixes |
| **Tier 12-13** | End-to-end validation | Full test suite, manual validation | Comprehensive debugging |

### Rollback Triggers

Rollback or pause migration if:

1. ✅ **Tier 2-4 failures**: Preview framework shows critical instability
2. ✅ **Tier 6 failure**: Database providers unusable
3. ✅ **>20% test failures** in any tier
4. ✅ **Performance degradation** >30% in benchmarks
5. ✅ **Blocking preview bugs** with no workaround
6. ✅ **Security vulnerabilities** in preview framework
7. ✅ **Critical runtime errors** not present in .NET 9.0

### Risk Acceptance

The following risks are **accepted**:

- ✅ **Preview framework instability**: Required for .NET 11.0 evaluation
- ✅ **Minor breaking changes**: Expected in preview; can be addressed
- ✅ **Performance variations**: Preview builds may have unoptimized code
- ✅ **Incomplete preview features**: Can work around or wait for releases

### Continuous Risk Monitoring

Throughout migration:
- Monitor .NET 11.0 preview announcements and known issues
- Track package update releases for compatibility fixes
- Performance benchmark each tier vs. .NET 9.0 baseline
- Document all issues encountered for future reference
- Maintain communication with .NET/EF Core/package maintainer communities

## Testing & Validation Strategy
[To be filled]

## Complexity & Effort Assessment

### Overall Complexity: **COMPLEX**

Based on solution structure, technology stack, and preview framework target.

### Per-Tier Complexity Assessment

| Tier | Projects | Complexity | Dependencies | Risk | Effort | Rationale |
|------|----------|------------|--------------|------|--------|-----------|
| **Tier 1** | 1 | N/A | None | None | None | No migration (netstandard2.0) |
| **Tier 2** | 3 | **Medium** | CodeAnalysis only | High | Medium | First preview exposure; database/extension infrastructure |
| **Tier 3** | 2 | **Low** | Tier 2 | Low | Low | Data models + 1 test; straightforward |
| **Tier 4** | 1 | **Medium** | Tiers 2-3 | Medium | Low | Central models (high fan-out); single project |
| **Tier 5** | 3 | **Low** | Tiers 2-4 | Low | Low | Common utilities + 2 tests; minimal complexity |
| **Tier 6** | 3 | **High** | Tiers 2-5 | **Critical** | High | Database providers (PostgreSQL, SQLite); extensive testing required |
| **Tier 7** | 2 | **Medium** | Tiers 2-6 | Medium | Medium | Controller abstractions + 1 test; moderate complexity |
| **Tier 8** | 12 | **High** | Tiers 2-7 | High | High | Largest tier; media processing, networking, business logic; parallelizable |
| **Tier 9** | 8 | **Medium** | Tiers 2-8 | Medium | Medium | API + 7 test projects; validation-heavy |
| **Tier 10** | 2 | **High** | Tiers 2-9 | High | High | Server implementations; integration point for all features |
| **Tier 11** | 1 | **High** | Tiers 2-10 | High | Medium | Main application; entry point; consolidates all functionality |
| **Tier 12** | 2 | **Medium** | Tier 11 | Medium | Medium | Integration tests; end-to-end validation |
| **Tier 13** | 1 | **Low** | Tier 12 | Low | Low | Final test project; single project validation |

### Tier-by-Tier Effort Breakdown

#### Low Complexity Tiers (4 tiers, 7 projects)
**Tiers**: 3, 5, 13  
**Total Projects**: 7  
**Characteristics**:
- Small codebases or test-only projects
- Minimal dependencies or simple utilities
- Straightforward migration
- Low risk of issues

**Estimated Effort**: Low per tier

---

#### Medium Complexity Tiers (5 tiers, 10 projects)
**Tiers**: 2, 4, 7, 9, 12  
**Total Projects**: 10  
**Characteristics**:
- Infrastructure components (Tier 2)
- Central models with high fan-out (Tier 4)
- Controller abstractions (Tier 7)
- API + multiple tests (Tier 9)
- Integration testing (Tier 12)

**Estimated Effort**: Medium per tier

---

#### High Complexity Tiers (3 tiers, 15 projects)
**Tiers**: 6, 8, 10, 11  
**Total Projects**: 15  
**Characteristics**:
- **Tier 6**: Database providers (CRITICAL; extensive testing)
- **Tier 8**: Largest tier (12 projects); media processing, networking, business logic
- **Tier 10**: Server implementations (integration complexity)
- **Tier 11**: Main application (consolidation point)

**Estimated Effort**: High per tier

### Resource Requirements

#### Skill Levels Needed

1. **Senior .NET Engineers** (Required)
   - Deep .NET framework knowledge
   - Experience with preview frameworks
   - EF Core expertise (for Tier 6)
   - ASP.NET Core experience (for Tiers 9-11)

2. **Database Engineers** (Tier 6)
   - PostgreSQL administration
   - SQLite expertise
   - EF Core migrations and performance tuning

3. **Media Processing Engineers** (Tier 8)
   - FFmpeg integration knowledge
   - Video encoding/transcoding experience
   - HLS streaming protocols

4. **QA/Testing Engineers** (All tiers)
   - Test framework expertise (xUnit)
   - Integration testing
   - Performance testing

#### Parallel Execution Capacity

**Optimal Team Structure**:
- **Tier 2-5, 7**: 1-2 engineers (sequential or small parallel)
- **Tier 6**: 2-3 engineers (database providers need dedicated focus)
- **Tier 8**: 3-5 engineers (12 projects; high parallelism potential)
- **Tier 9-11**: 2-3 engineers (integration complexity)
- **Tier 12-13**: 1-2 engineers (testing focus)

**Minimum Team**: 2 senior .NET engineers + 1 QA engineer  
**Optimal Team**: 4-5 engineers (mix of specializations) + 2 QA engineers

### Phase Complexity Summary

| Phase | Tier(s) | Complexity | Effort | Duration Estimate |
|-------|---------|------------|--------|-------------------|
| **Phase 1** | Tier 2 | Medium | Medium | *Relative: Medium* |
| **Phase 2** | Tier 3 | Low | Low | *Relative: Low* |
| **Phase 3** | Tier 4 | Medium | Low | *Relative: Low* |
| **Phase 4** | Tier 5 | Low | Low | *Relative: Low* |
| **Phase 5** | Tier 6 | **High** | **High** | *Relative: High* |
| **Phase 6** | Tier 7 | Medium | Medium | *Relative: Medium* |
| **Phase 7** | Tier 8 | **High** | **High** | *Relative: High* |
| **Phase 8** | Tier 9 | Medium | Medium | *Relative: Medium* |
| **Phase 9** | Tier 10 | **High** | **High** | *Relative: High* |
| **Phase 10** | Tier 11 | High | Medium | *Relative: Medium* |
| **Phase 11** | Tier 12 | Medium | Medium | *Relative: Medium* |
| **Phase 12** | Tier 13 | Low | Low | *Relative: Low* |
| **Phase 13** | All | High | High | *Relative: High* |

**Note**: Duration estimates are relative complexity ratings only. Actual time depends on team size, experience, issue discovery, and preview framework stability.

### Complexity Factors by Tier

#### Tier 2: Core Infrastructure (Medium)
- **Factors**:
  - First exposure to .NET 11.0 preview
  - Database implementation foundation
  - Extension infrastructure
- **Challenges**:
  - Unknown preview framework issues
  - Critical foundation for all higher tiers
- **Mitigation**: Thorough testing; early warning system

#### Tier 6: Database Providers (High) ⚠️ CRITICAL
- **Factors**:
  - PostgreSQL EF Core provider (preview)
  - SQLite EF Core provider (preview)
  - Database operations throughout solution depend on this
- **Challenges**:
  - Provider preview stability
  - Query translation, migrations, performance
  - Concurrent operations, connection pooling
- **Mitigation**: Extensive integration testing, performance benchmarking

#### Tier 8: Business Logic (High)
- **Factors**:
  - 12 projects (largest tier)
  - Media processing (SkiaSharp, FFmpeg)
  - Networking (DLNA, SSDP)
  - Providers, metadata, encoding
- **Challenges**:
  - Diverse functionality requiring different expertise
  - Native library interop (SkiaSharp)
  - Process management (FFmpeg)
- **Mitigation**: Parallelization; specialized testing per area

#### Tier 10: Server Implementation (High)
- **Factors**:
  - Emby.Server.Implementations (14 dependencies)
  - Integration point for most features
- **Challenges**:
  - Complex integration
  - Many failure points from dependencies
- **Mitigation**: Tiers 2-9 stable; incremental testing

#### Tier 11: Main Application (High)
- **Factors**:
  - Application entry point
  - ASP.NET Core 11.0 hosting
  - Startup, middleware, DI configuration
- **Challenges**:
  - All features converge here
  - ASP.NET Core preview stability
- **Mitigation**: Comprehensive smoke testing; staging environment validation

### Incremental Benefit Realization

Benefits realized after each tier completion:

| Tier Complete | Benefits Unlocked |
|---------------|-------------------|
| **Tier 2** | Foundation infrastructure on .NET 11.0; preview framework viability assessed |
| **Tier 3** | Data models available to higher tiers |
| **Tier 4** | Central models on .NET 11.0; broad compatibility established |
| **Tier 5** | Common utilities available; model validation complete |
| **Tier 6** | **Database providers validated** (critical milestone); data access stable |
| **Tier 7** | Controller abstractions ready; naming validated |
| **Tier 8** | **Business logic on .NET 11.0**; media processing, networking validated |
| **Tier 9** | **API layer operational**; comprehensive business logic tests pass |
| **Tier 10** | **Server implementations complete**; integration validated |
| **Tier 11** | **Main application functional**; end-to-end features available |
| **Tier 12** | **Integration testing complete**; confidence in full stack |
| **Tier 13** | **All tests pass**; solution fully validated |

### Critical Milestones

1. **Tier 2 Complete**: Preview framework viability confirmed
2. **Tier 6 Complete**: Database providers stable (go/no-go decision point)
3. **Tier 8 Complete**: Business logic operational
4. **Tier 11 Complete**: Application functional
5. **Tier 13 Complete**: Full solution validation

### Effort Distribution

- **Low Effort Tiers** (3, 5, 13): ~15% of total effort
- **Medium Effort Tiers** (2, 4, 7, 9, 12): ~35% of total effort
- **High Effort Tiers** (6, 8, 10, 11): ~50% of total effort

**Highest effort areas**:
1. Tier 6 (Database providers) - CRITICAL
2. Tier 8 (Business logic) - Largest tier
3. Tier 10-11 (Server & application) - Integration complexity

## Source Control Strategy

### Branching Strategy

**Primary Branch**: `upgrade-to-NET11`  
**Source Branch**: `pgsql_testing_branch`  
**Merge Target**: `pgsql_testing_branch` (after successful validation)

#### Branch Management
- Upgrade branch created from `pgsql_testing_branch`
- All migration work on `upgrade-to-NET11`
- Tier-by-tier commits
- Protected milestones: Tags after Tier 6, Tier 11, Tier 13

### Commit Strategy

**Format**: `Upgrade Tier [N] ([Name]) to .NET 11.0`

**Per-Tier Commits** (Recommended):
- One commit per tier
- Atomic changes
- Includes test validation

### Review and Merge

**Single PR** after complete validation (recommended for preview framework)

**PR Checklist**:
- [ ] All 13 tiers complete
- [ ] 100% test pass rate
- [ ] Full solution builds clean
- [ ] Performance acceptable
- [ ] Documentation updated

**Review Requirements**: 2+ senior engineers

### Rollback Plan

**Triggers**: Critical preview bugs, database failures, severe performance degradation

**Method**: Git revert to pre-migration state

---

## Success Criteria

### Technical Criteria

**Build & Compilation**:
- ✅ 40 projects upgraded to .NET 11.0
- ✅ Solution builds without errors/warnings
- ✅ No package conflicts

**Testing**:
- ✅ All 15 test projects: 100% pass rate
- ✅ No flaky tests

**Database Providers (CRITICAL)**:
- ✅ PostgreSQL & SQLite functional
- ✅ Migrations successful
- ✅ Performance: <10% regression

**Application**:
- ✅ Jellyfin.Server starts
- ✅ All major features work
- ✅ API functional

**Performance**:
- ✅ Startup: <20% regression
- ✅ Database queries: <10% regression
- ✅ API/processing: <15% regression
- ✅ Memory: <15% increase

**Code Quality**:
- ✅ All analyzers pass
- ✅ No new warnings

**Bottom-Up Strategy**:
- ✅ All 13 tiers completed in order
- ✅ Tier 6 extensively validated

**Deployment**:
- ✅ Deploys to target platforms
- ✅ Rollback tested

### Definition of Done

Migration complete when:
- All technical criteria met
- All stakeholder approvals obtained
- PR merged
- Post-merge validation passed

---

## Final Notes

### .NET 11.0 Preview Warning

Targeting **PREVIEW framework** - expect instability. Monitor closely; consider .NET 10.0 LTS if critical issues arise.

### Post-Migration

1. Monitor .NET 11.0 release progression
2. Update to stable package versions
3. Performance tuning
4. Report issues to .NET team

---

**Plan Version**: 1.0  
**Target**: .NET 11.0 (PREVIEW)  
**Strategy**: Bottom-Up (Dependency-First)  
**Tiers**: 13 (Tier 1 unchanged, Tiers 2-13 migrated)
