EnvelopeGenerator/MIGRATION_CONTEXT.md

# EnvelopeGenerator.ReceiverUI ? WebUI Migration Context

## ?? Migration Purpose

### Problem Statement
**DevExpress `DxPdfViewer` component does NOT work in pure Blazor WebAssembly (standalone) mode.**

**Symptoms:**
- PDF file loads successfully (byte array received)
- Component renders (no errors in console)
- **Result: Blank/white screen** - PDF is not displayed

**Root Cause:**
DevExpress `DxPdfViewer` requires **backend server-side rendering services** that are NOT available in pure WebAssembly projects (`Microsoft.NET.Sdk.BlazorWebAssembly`).

**Solution:**
Migrate from **pure Blazor WebAssembly** (`ReceiverUI`) to **Blazor Auto (Server+WASM hybrid)** (`WebUI`) architecture.

---

## ?? Current vs. Target Architecture

### Current Architecture (PROBLEMATIC)
```
Client Browser
    ?
EnvelopeGenerator.API:8088 (YARP Proxy)
    ?
EnvelopeGenerator.ReceiverUI:52936 (Pure Blazor WebAssembly)
    ??? SDK: Microsoft.NET.Sdk.BlazorWebAssembly
    ??? DxPdfViewer ? ? WHITE SCREEN (no backend)
    ??? All pages run client-side only
```

### Target Architecture (SOLUTION)
```
Client Browser
    ?
EnvelopeGenerator.WebUI:XXXX (Blazor Auto - Server+WASM)
    ??? YARP Proxy: /api/* ? API:8088
    ??? YARP Proxy: /swagger/* ? API:8088
    ??? Server-side Pages (@rendermode InteractiveServer)
    ?   ??? DxPdfViewer pages ? ? WORKS (backend available)
    ??? Client-side Pages (@rendermode InteractiveWebAssembly)
        ??? Login, Sender, Index pages
```

---

## ??? Project Structure

### EnvelopeGenerator.WebUI (Server Project)
**Path:** `EnvelopeGenerator.WebUI\EnvelopeGenerator.WebUI\`
**SDK:** `Microsoft.NET.Sdk.Web`
**Target:** `net8.0`

**Responsibilities:**
1. **YARP Reverse Proxy**
   - Routes `/api/*` to `API:8088`
   - Routes `/swagger/*`, `/openapi/*`, `/scalar/*` to `API:8088`
   - All other routes handled by Blazor components

2. **DevExpress Server-Side Services**
   - `AddDevExpressServerSideBlazorPdfViewer()` - **CRITICAL for DxPdfViewer**
   - `AddDevExpressBlazorReportViewer()` - For DxReportViewer
   - Provides backend rendering engine

3. **Static File Hosting**
   - Serves `wwwroot/` (JS, CSS, PDF.js)
   - Hosts PDF viewer assets

4. **Server-Side Components**
   - `@rendermode InteractiveServer` pages
   - PDF viewer pages (EnvelopeReceiverPage*.razor)

**Key Files:**
- `Program.cs` - YARP + DevExpress server configuration
- `yarp.json` - Proxy route definitions
- `Components/App.razor` - Root component
- `Components/Routes.razor` - Routing configuration
- `Pages/EnvelopeReceiverPage*.razor` - Server-side PDF viewers

**NuGet Packages:**
```xml
<PackageReference Include="Yarp.ReverseProxy" Version="2.1.0" />
<PackageReference Include="DevExpress.Blazor" Version="25.2.3" />
<PackageReference Include="DevExpress.Blazor.PdfViewer" Version="25.2.3" />
<PackageReference Include="DevExpress.Blazor.Reporting.Viewer" Version="25.2.3" />
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Server" Version="8.0.22" />
```

---

### EnvelopeGenerator.WebUI.Client (WASM Project)
**Path:** `EnvelopeGenerator.WebUI\EnvelopeGenerator.WebUI.Client\`
**SDK:** `Microsoft.NET.Sdk.BlazorWebAssembly`
**Target:** `net8.0`

**Responsibilities:**
1. **Client-Side Pages**
   - `@rendermode InteractiveWebAssembly` components
   - Authentication pages (Login)
   - Public pages (Index)
   - Sender dashboard

2. **Business Logic Services**
   - All services (AuthService, DocumentService, etc.)
   - API communication via HttpClient
   - Signature caching

3. **DevExpress WASM Components**
   - Client-side DevExpress components
   - Reporting tools

**Key Files:**
- `Program.cs` - Service registration + DevExpress WASM
- `Pages/Index.razor` - Landing page
- `Pages/LoginSenderPage.razor` - Sender authentication
- `Pages/LoginReceiverPage.razor` - Receiver authentication
- `Pages/EnvelopeSenderPage.razor` - Sender dashboard
- `Services/*` - All business logic services

**NuGet Packages:**
```xml
<PackageReference Include="DevExpress.Blazor.PdfViewer" Version="25.2.3" />
<PackageReference Include="DevExpress.Blazor.Reporting.JSBasedControls" Version="25.2.3" />
<PackageReference Include="DevExpress.Blazor.Reporting.Viewer" Version="25.2.3" />
<PackageReference Include="DevExpress.Drawing.Skia" Version="25.2.3" />
<PackageReference Include="HarfBuzzSharp.NativeAssets.WebAssembly" Version="8.3.1.2" />
<PackageReference Include="SkiaSharp.NativeAssets.WebAssembly" Version="3.119.1" />
<PackageReference Include="SkiaSharp.Views.Blazor" Version="3.119.1" />
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="8.0.11" />
```

---

### EnvelopeGenerator.ReceiverUI (OLD - Will Remain for Now)
**Path:** `EnvelopeGenerator.ReceiverUI\`
**Status:** ?? **DEPRECATED but NOT deleted during migration**
**SDK:** `Microsoft.NET.Sdk.BlazorWebAssembly`

**Migration Plan:**
- Files will be **COPIED** to WebUI/WebUI.Client (not moved)
- Original ReceiverUI project will **remain untouched** during migration
- Can be deleted later after successful migration verification

---

## ?? File Migration Map

### Client-Side Pages (ReceiverUI ? WebUI.Client)
| Source File | Destination | Render Mode | Action |
|-------------|-------------|-------------|--------|
| `ReceiverUI/Pages/Index.razor` | `WebUI.Client/Pages/Index.razor` | `@rendermode InteractiveWebAssembly` | **COPY** |
| `ReceiverUI/Pages/EnvelopeSenderPage.razor` | `WebUI.Client/Pages/EnvelopeSenderPage.razor` | `@rendermode InteractiveWebAssembly` | **COPY** |
| `ReceiverUI/Pages/LoginSenderPage.razor` | `WebUI.Client/Pages/LoginSenderPage.razor` | `@rendermode InteractiveWebAssembly` | **COPY** |
| `ReceiverUI/Pages/LoginReceiverPage.razor` | `WebUI.Client/Pages/LoginReceiverPage.razor` | `@rendermode InteractiveWebAssembly` | **COPY** |

**Post-Migration Edit:**
Add `@rendermode InteractiveWebAssembly` to the top of each file (after `@page` directive).

---

### Server-Side PDF Viewer Pages (ReceiverUI ? WebUI)
| Source File | Destination | Render Mode | Action |
|-------------|-------------|-------------|--------|
| `ReceiverUI/Pages/EnvelopeReceiverPage.razor` | `WebUI/Pages/EnvelopeReceiverPage.razor` | `@rendermode InteractiveServer` | **COPY** |
| `ReceiverUI/Pages/EnvelopeReceiverPage_DxPdfViewer.razor` | `WebUI/Pages/EnvelopeReceiverPage_DxPdfViewer.razor` | `@rendermode InteractiveServer` | **COPY** |
| `ReceiverUI/Pages/EnvelopeReceiverPage_DxReportViewer.razor` | `WebUI/Pages/EnvelopeReceiverPage_DxReportViewer.razor` | `@rendermode InteractiveServer` | **COPY** |
| `ReceiverUI/Pages/EnvelopeReceiverPage_embed.razor` | `WebUI/Pages/EnvelopeReceiverPage_embed.razor` | `@rendermode InteractiveServer` | **COPY** |

**Why Server-Side?**
- DevExpress `DxPdfViewer` **requires** backend rendering
- `DxReportViewer` also needs server-side services
- `@rendermode InteractiveServer` provides SignalR connection to backend

**Post-Migration Edit:**
1. Add `@rendermode InteractiveServer` to top of file
2. Update `@using` directives to reference `WebUI.Client` namespaces

---

### Services (ReceiverUI ? WebUI.Client)
| Source Directory | Destination | Action |
|------------------|-------------|--------|
| `ReceiverUI/Services/AuthService.cs` | `WebUI.Client/Services/AuthService.cs` | **COPY** |
| `ReceiverUI/Services/DocumentService.cs` | `WebUI.Client/Services/DocumentService.cs` | **COPY** |
| `ReceiverUI/Services/SignatureService.cs` | `WebUI.Client/Services/SignatureService.cs` | **COPY** |
| `ReceiverUI/Services/SignatureCacheService.cs` | `WebUI.Client/Services/SignatureCacheService.cs` | **COPY** |
| `ReceiverUI/Services/EnvelopeReceiverService.cs` | `WebUI.Client/Services/EnvelopeReceiverService.cs` | **COPY** |
| `ReceiverUI/Services/AnnotationService.cs` | `WebUI.Client/Services/AnnotationService.cs` | **COPY** |
| `ReceiverUI/Services/AppVersionService.cs` | `WebUI.Client/Services/AppVersionService.cs` | **COPY** |
| `ReceiverUI/Services/CustomDataSourceWizardJsonDataConnectionStorage.cs` | `WebUI.Client/Services/CustomDataSourceWizardJsonDataConnectionStorage.cs` | **COPY** |
| `ReceiverUI/Services/CustomJsonDataConnectionProviderFactory.cs` | `WebUI.Client/Services/CustomJsonDataConnectionProviderFactory.cs` | **COPY** |
| `ReceiverUI/Services/CustomReportProvider.cs` | `WebUI.Client/Services/CustomReportProvider.cs` | **COPY** |
| `ReceiverUI/Services/FontLoader.cs` | `WebUI.Client/Services/FontLoader.cs` | **COPY** |
| `ReceiverUI/Services/InMemoryReportStorageWebExtension.cs` | `WebUI.Client/Services/InMemoryReportStorageWebExtension.cs` | **COPY** |
| `ReceiverUI/Services/ObjectDataSourceWizardCustomTypeProvider.cs` | `WebUI.Client/Services/ObjectDataSourceWizardCustomTypeProvider.cs` | **COPY** |

**Post-Migration Edit:**
Update namespace from `EnvelopeGenerator.ReceiverUI.Services` to `EnvelopeGenerator.WebUI.Client.Services`

---

### Models, Options, Data (ReceiverUI ? WebUI.Client)
| Source Directory | Destination | Action |
|------------------|-------------|--------|
| `ReceiverUI/Models/*` | `WebUI.Client/Models/*` | **COPY ALL FILES** |
| `ReceiverUI/Options/*` | `WebUI.Client/Options/*` | **COPY ALL FILES** |
| `ReceiverUI/Data/*` | `WebUI.Client/Data/*` | **COPY ALL FILES** |
| `ReceiverUI/Shared/*` | `WebUI.Client/Shared/*` | **COPY ALL FILES** |

**Post-Migration Edit:**
Update namespaces to `EnvelopeGenerator.WebUI.Client.*`

---

### Static Files (ReceiverUI ? WebUI)
| Source | Destination | Action |
|--------|-------------|--------|
| `ReceiverUI/wwwroot/js/*` | `WebUI/wwwroot/js/*` | **MERGE** (keep both if conflict) |
| `ReceiverUI/wwwroot/css/*` | `WebUI/wwwroot/css/*` | **MERGE** |
| `ReceiverUI/wwwroot/docs/*` | `WebUI/wwwroot/docs/*` | **MERGE** |
| `ReceiverUI/wwwroot/appsettings.json` | `WebUI/wwwroot/appsettings.json` | **MERGE** (combine PdfViewerOptions) |
| `ReceiverUI/wwwroot/appsettings.Development.json` | `WebUI/wwwroot/appsettings.Development.json` | **MERGE** |

**Critical Files:**
- `js/pdf-viewer.js` - PDF.js wrapper
- `js/receiver-signature.js` - Signature pad
- `css/envelope-viewer.css` - Viewer styles
- `appsettings.json` - PdfViewerOptions configuration

---

### _Imports.razor (ReceiverUI ? WebUI.Client)
| Source | Destination | Action |
|--------|-------------|--------|
| `ReceiverUI/_Imports.razor` | `WebUI.Client/_Imports.razor` | **MERGE** (combine using directives) |

**Post-Migration Content:**
```razor
@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using EnvelopeGenerator.WebUI.Client
@using EnvelopeGenerator.WebUI.Client.Services
@using EnvelopeGenerator.WebUI.Client.Models
@using EnvelopeGenerator.WebUI.Client.Options
@using DevExpress.Blazor
@using DevExpress.Blazor.PdfViewer
@using DevExpress.Blazor.Reporting
```

---

### Excluded Files (NOT Migrated)
| Source Directory | Reason |
|------------------|--------|
| `ReceiverUI/Pages/Example/*` | Test pages, not needed in production |
| `ReceiverUI/PredefinedReports/*` | Deprecated, reports moved to WebUI.Client/Data |

---

## ?? YARP Configuration

### WebUI/yarp.json (NEW FILE)
```json
{
  "ReverseProxy": {
    "Routes": {
      "api-route": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "/api/{**catch-all}"
        }
      },
      "swagger-route": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "/swagger/{**catch-all}"
        }
      },
      "openapi-route": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "/openapi/{**catch-all}"
        }
      },
      "scalar-route": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "/scalar/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "api-cluster": {
        "Destinations": {
          "api-destination": {
            "Address": "https://localhost:8088"
          }
        }
      }
    }
  }
}
```

**Purpose:**
- Route all `/api/*` requests to backend API
- Route Swagger/OpenAPI to API (development only)
- All other requests handled by Blazor components

**Configuration Location:**
Place `yarp.json` in `EnvelopeGenerator.WebUI\EnvelopeGenerator.WebUI\` directory.

**Important:**
Set **Copy to Output Directory** to `Copy if newer` in file properties.

---

### API/yarp.json (MODIFICATION)
**Current State:**
API currently proxies requests to ReceiverUI:52936

**Target State:**
API will **NOT have YARP** - all proxying moves to WebUI

**Action:**
- **DO NOT DELETE** `API/yarp.json` during migration
- Keep for rollback safety
- Can comment out YARP code in `API/Program.cs` instead of deleting

---

## ?? Configuration Files

### WebUI/appsettings.json
```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiOptions": {
    "BaseUrl": ""
  },
  "PdfViewerOptions": {
    "ThumbnailBaseScale": 0.75,
    "ThumbnailEnableHiDPI": true,
    "MainCanvasEnableHiDPI": true,
    "ZoomStepPercentage": 5
  }
}
```

**Critical Setting:**
`"BaseUrl": ""` - Empty because YARP handles proxy automatically (requests to `/api/*` are proxied)

---

### WebUI/wwwroot/appsettings.json (Client-Side Config)
```json
{
  "ApiOptions": {
    "BaseUrl": ""
  },
  "PdfViewerOptions": {
    "ThumbnailBaseScale": 0.75,
    "ThumbnailEnableHiDPI": true,
    "ThumbnailMaxDPR": 4.0,
    "MainCanvasEnableHiDPI": true,
    "MainCanvasMaxDPR": 4.0,
    "EnableSmoothZoom": true,
    "ZoomTransitionDuration": 200,
    "RenderingOpacity": 1.0,
    "ZoomStepPercentage": 5,
    "ThumbnailRenderDelay": 25
  }
}
```

**Purpose:**
Configures PDF.js quality settings for optimal rendering.

---

## ?? Render Mode Strategy

### When to Use `@rendermode InteractiveServer`
**Use Cases:**
- PDF viewer pages (DxPdfViewer, DxReportViewer)
- Any page using DevExpress components requiring backend
- Pages with heavy server-side logic

**Example:**
```razor
@page "/envelope/{EnvelopeKey}"
@rendermode InteractiveServer
@using DevExpress.Blazor.PdfViewer
@using EnvelopeGenerator.WebUI.Client.Services
...
```

**Why:**
DevExpress `DxPdfViewer` calls server-side APIs for PDF rendering. Server render mode provides SignalR connection to backend.

---

### When to Use `@rendermode InteractiveWebAssembly`
**Use Cases:**
- Authentication pages (no sensitive data on client)
- Public pages (landing, index)
- Pages with pure client-side logic
- Sender dashboard (calls API via HttpClient)

**Example:**
```razor
@page "/sender/login"
@rendermode InteractiveWebAssembly
@using EnvelopeGenerator.WebUI.Client.Services
...
```

**Why:**
No server-side dependencies, reduces server load, works offline (PWA).

---

## ?? Service Registration

### WebUI/Program.cs (Server)
```csharp
using DevExpress.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Load YARP configuration
builder.Configuration.AddJsonFile("yarp.json", optional: false, reloadOnChange: true);

// Blazor Components
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

// YARP Reverse Proxy
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

// DevExpress Server-Side Services (CRITICAL for DxPdfViewer)
builder.Services.AddDevExpressBlazor(configure => configure.BootstrapVersion = BootstrapVersion.v5);
builder.Services.AddDevExpressServerSideBlazorPdfViewer();
builder.Services.AddDevExpressBlazorReportViewer();

// Configuration Options
builder.Services.Configure<EnvelopeGenerator.WebUI.Client.Options.ApiOptions>(
    builder.Configuration.GetSection("ApiOptions"));
builder.Services.Configure<EnvelopeGenerator.WebUI.Client.Options.PdfViewerOptions>(
    builder.Configuration.GetSection("PdfViewerOptions"));

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAntiforgery();

// Blazor routing (BEFORE YARP)
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(EnvelopeGenerator.WebUI.Client._Imports).Assembly);

// YARP proxy (AFTER Blazor - catch-all)
app.MapReverseProxy();

app.Run();
```

**Critical Order:**
1. `MapRazorComponents` first (Blazor routes)
2. `MapReverseProxy` last (catch-all for `/api/*`)

---

### WebUI.Client/Program.cs (WASM)
```csharp
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using EnvelopeGenerator.WebUI.Client.Services;
using EnvelopeGenerator.WebUI.Client.Options;
using DevExpress.Blazor.Reporting;
using DevExpress.XtraReports.Web.Extensions;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

// HTTP Client (uses WebUI's YARP proxy)
builder.Services.AddScoped(sp => new HttpClient { 
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) 
});

// Configuration Options
builder.Services.Configure<ApiOptions>(
    builder.Configuration.GetSection(ApiOptions.SectionName));
builder.Services.Configure<PdfViewerOptions>(
    builder.Configuration.GetSection(PdfViewerOptions.SectionName));

// Business Services
builder.Services.AddScoped<DocumentService>();
builder.Services.AddScoped<AuthService>();
builder.Services.AddScoped<AnnotationService>();
builder.Services.AddScoped<EnvelopeReceiverService>();
builder.Services.AddScoped<SignatureService>();
builder.Services.AddScoped<SignatureCacheService>();
builder.Services.AddSingleton<AppVersionService>();

// DevExpress WASM
builder.Services.AddDevExpressWebAssemblyBlazorPdfViewer();
builder.Services.AddDevExpressWebAssemblyBlazorReportViewer();

builder.Services.AddDevExpressBlazorReportingWebAssembly(configure => {
    configure.UseDevelopmentMode();
});

// Reporting Services
builder.Services.AddScoped<IDataSourceWizardJsonConnectionStorage, CustomDataSourceWizardJsonDataConnectionStorage>();
builder.Services.AddScoped<IJsonDataConnectionProviderFactory, CustomJsonDataConnectionProviderFactory>();
builder.Services.AddScoped<IObjectDataSourceWizardTypeProvider, ObjectDataSourceWizardCustomTypeProvider>();

DevExpress.Utils.DeserializationSettings.RegisterTrustedClass(typeof(EnvelopeGenerator.WebUI.Client.Data.DataItemList));
DevExpress.Utils.DeserializationSettings.RegisterTrustedClass(typeof(EnvelopeGenerator.WebUI.Client.PredefinedReports.Report));

builder.Services.AddSingleton<InMemoryReportStorageWebExtension>();
builder.Services.AddSingleton<ReportStorageWebExtension>(sp => sp.GetRequiredService<InMemoryReportStorageWebExtension>());
builder.Services.AddScoped<IReportProviderAsync, CustomReportProvider>();

ReportStorageWebExtension.RegisterExtensionGlobal(new InMemoryReportStorageWebExtension());

await builder.Build().RunAsync();
```

---

## ? Migration Checklist

### Phase 1: WebUI YARP Setup
- [ ] Create `WebUI/yarp.json`
- [ ] Add YARP NuGet package to `WebUI.csproj`
- [ ] Update `WebUI/Program.cs` with YARP configuration
- [ ] Add DevExpress server packages to `WebUI.csproj`
- [ ] Create `WebUI/appsettings.json` with `ApiOptions.BaseUrl = ""`

### Phase 2: File Migration - Client Pages
- [ ] Copy `ReceiverUI/Pages/Index.razor` ? `WebUI.Client/Pages/`
- [ ] Copy `ReceiverUI/Pages/EnvelopeSenderPage.razor` ? `WebUI.Client/Pages/`
- [ ] Copy `ReceiverUI/Pages/LoginSenderPage.razor` ? `WebUI.Client/Pages/`
- [ ] Copy `ReceiverUI/Pages/LoginReceiverPage.razor` ? `WebUI.Client/Pages/`
- [ ] Add `@rendermode InteractiveWebAssembly` to each file

### Phase 3: File Migration - Server Pages
- [ ] Copy `ReceiverUI/Pages/EnvelopeReceiverPage.razor` ? `WebUI/Pages/`
- [ ] Copy `ReceiverUI/Pages/EnvelopeReceiverPage_DxPdfViewer.razor` ? `WebUI/Pages/`
- [ ] Copy `ReceiverUI/Pages/EnvelopeReceiverPage_DxReportViewer.razor` ? `WebUI/Pages/`
- [ ] Copy `ReceiverUI/Pages/EnvelopeReceiverPage_embed.razor` ? `WebUI/Pages/`
- [ ] Add `@rendermode InteractiveServer` to each file
- [ ] Update `@using` directives to `WebUI.Client` namespaces

### Phase 4: File Migration - Services
- [ ] Copy `ReceiverUI/Services/*` ? `WebUI.Client/Services/`
- [ ] Update namespaces to `EnvelopeGenerator.WebUI.Client.Services`

### Phase 5: File Migration - Models/Options/Data
- [ ] Copy `ReceiverUI/Models/*` ? `WebUI.Client/Models/`
- [ ] Copy `ReceiverUI/Options/*` ? `WebUI.Client/Options/`
- [ ] Copy `ReceiverUI/Data/*` ? `WebUI.Client/Data/`
- [ ] Copy `ReceiverUI/Shared/*` ? `WebUI.Client/Shared/`
- [ ] Update all namespaces to `EnvelopeGenerator.WebUI.Client.*`

### Phase 6: File Migration - Static Files
- [ ] Merge `ReceiverUI/wwwroot/js/*` ? `WebUI/wwwroot/js/`
- [ ] Merge `ReceiverUI/wwwroot/css/*` ? `WebUI/wwwroot/css/`
- [ ] Merge `ReceiverUI/wwwroot/docs/*` ? `WebUI/wwwroot/docs/`
- [ ] Merge `ReceiverUI/wwwroot/appsettings.json` ? `WebUI/wwwroot/appsettings.json`

### Phase 7: Configuration
- [ ] Add DevExpress WASM packages to `WebUI.Client.csproj`
- [ ] Update `WebUI.Client/Program.cs` with service registrations
- [ ] Merge `ReceiverUI/_Imports.razor` ? `WebUI.Client/_Imports.razor`
- [ ] Set `yarp.json` to "Copy if newer" in file properties

### Phase 8: Testing
- [ ] Build `WebUI` project ? No errors
- [ ] Build `WebUI.Client` project ? No errors
- [ ] Run `WebUI` ? Application starts
- [ ] Test YARP: `/api/*` routes to API:8088
- [ ] Test `/sender/login` ? Login page works
- [ ] Test `/envelope/DxPdfViewer` ? **PDF displays (not blank!)**
- [ ] Test `/envelope/{key}` ? PDF.js viewer works
- [ ] Test signature caching
- [ ] Test authentication cookies
- [ ] No CORS errors in browser console

---

## ?? Critical Notes

### 1. DO NOT DELETE ReceiverUI During Migration
- Keep `EnvelopeGenerator.ReceiverUI` project untouched
- Files are **COPIED**, not moved
- Allows rollback if migration fails
- Can be deleted after successful verification

### 2. API YARP Modification Strategy
- **DO NOT delete** `API/yarp.json` immediately
- Comment out YARP code in `API/Program.cs` instead
- Keep for rollback safety
- Remove only after WebUI proven stable

### 3. Namespace Updates Are CRITICAL
- All copied files must update namespaces
- `EnvelopeGenerator.ReceiverUI.*` ? `EnvelopeGenerator.WebUI.Client.*`
- Missing namespace updates = compilation errors

### 4. Render Mode MUST Match Component Type
- Server-side DevExpress ? `@rendermode InteractiveServer`
- Client-side pages ? `@rendermode InteractiveWebAssembly`
- Wrong render mode = component won't work

### 5. Service Registration Must Be Complete
- All ReceiverUI services ? `WebUI.Client/Program.cs`
- Missing service = runtime injection errors
- Check DI container for all dependencies

### 6. YARP Route Order Matters
```csharp
app.MapRazorComponents<App>()...;  // FIRST - Blazor routes
app.MapReverseProxy();              // LAST - Catch-all API proxy
```
Wrong order = `/api/*` requests handled by Blazor (404 errors)

### 7. wwwroot/ Merge Strategy
- **DO NOT overwrite** existing WebUI files
- Compare manually before merge
- Prioritize ReceiverUI files (they're tested)
- Keep both if conflict, rename WebUI version

---

## ?? Rollback Plan

If migration fails:

### Immediate Rollback
1. Stop `WebUI` application
2. Restore `API/Program.cs` YARP code
3. Start `ReceiverUI` + `API` as before
4. System operational again

### Permanent Rollback
1. Checkout previous Git commit
2. Discard all `WebUI` changes
3. Delete copied files from `WebUI.Client`
4. Resume development on `ReceiverUI`

### Partial Rollback
1. Keep `WebUI` structure
2. Revert YARP changes only
3. Continue using `ReceiverUI` while debugging `WebUI`

---

## ?? Success Criteria

Migration is successful when:

- [ ] `WebUI` application starts without errors
- [ ] `/api/*` requests proxied to API:8088
- [ ] `/envelope/DxPdfViewer` displays PDF (not blank!)
- [ ] `/envelope/{key}` PDF.js viewer works
- [ ] Login pages functional (Sender, Receiver)
- [ ] Sender dashboard loads
- [ ] Signature caching works
- [ ] Authentication cookies work
- [ ] No CORS errors
- [ ] No console errors
- [ ] Performance acceptable (not slower than ReceiverUI)

---

## ?? Known Issues & Workarounds

### Issue 1: DxPdfViewer Still Blank
**Cause:** Missing DevExpress server-side services
**Fix:** Verify `AddDevExpressServerSideBlazorPdfViewer()` in `WebUI/Program.cs`

### Issue 2: 404 on /api/* Requests
**Cause:** YARP not configured or wrong route order
**Fix:** Check `yarp.json` exists and `MapReverseProxy()` is AFTER `MapRazorComponents()`

### Issue 3: Services Not Injected
**Cause:** Missing service registration in `WebUI.Client/Program.cs`
**Fix:** Copy ALL service registrations from `ReceiverUI/Program.cs`

### Issue 4: Namespace Errors
**Cause:** Namespace not updated after file copy
**Fix:** Find/Replace `EnvelopeGenerator.ReceiverUI` ? `EnvelopeGenerator.WebUI.Client`

### Issue 5: Static Files Not Loading
**Cause:** `wwwroot/` not merged correctly
**Fix:** Check file paths, ensure files copied to `WebUI/wwwroot/`

---

## ?? Git Workflow

### Branch Strategy
- **Current Branch:** `bugfix/devexpress-pdf-not-displaying`
- **Remote:** `https://git.dd/AppStd/EnvelopeGenerator`

### Commit Strategy
1. Commit after each phase (incremental changes)
2. Descriptive commit messages
3. Tag final working version: `v1.0.0-webui-migration`

### Example Commits
```
feat(webui): add YARP configuration for API proxy
feat(webui): migrate client-side pages from ReceiverUI
feat(webui): migrate server-side PDF viewer pages
feat(webui): migrate services and models
feat(webui): merge static files and configuration
fix(webui): update namespaces to WebUI.Client
test(webui): verify DxPdfViewer rendering
docs(migration): add MIGRATION_CONTEXT.md
```

---

## ?? Learning Resources

### DevExpress Blazor Render Modes
https://docs.devexpress.com/Blazor/403507/blazor-components-render-modes

### YARP Documentation
https://microsoft.github.io/reverse-proxy/

### Blazor Auto (InteractiveAuto) Mode
https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes

---

**Migration Status:** ? **READY TO START**  
**Last Updated:** 2025-01-XX  
**Responsible:** AI Agent + Developer  
**Estimated Time:** 4-6 hours  
**Risk Level:** Medium (rollback available)

---

## ?? Support

**Questions?** Contact the development team or refer to:
- `COPILOT_CONTEXT.md` - Overall project context
- `FORM_APPLICATION_CONTEXT.md` - Legacy VB.NET app context
- DevExpress Support Portal

---

**END OF MIGRATION CONTEXT**