EnvelopeGenerator/AGENTS.md

EnvelopeGenerator - Agent Guide

Must Read First

• COPILOT_CONTEXT.md - Architecture, coordinate systems, migration status
• FORM_APPLICATION_CONTEXT.md - Legacy VB.NET features to migrate

Active Architecture (Post-Migration)

Frontend: Blazor Auto (Server+WASM hybrid)

• WebUI (Server): @rendermode InteractiveServer - PDF viewers requiring DevExpress backend
• WebUI.Client (WASM): @rendermode InteractiveWebAssembly - Login, dashboards, business logic

Backend: EnvelopeGenerator.API (ASP.NET Core 8.0)

Proxy: YARP in WebUI routes /api/* → localhost:8088 (API)

Deprecated Projects - DO NOT USE

• EnvelopeGenerator.ReceiverUI - Pure WASM (migrated to WebUI)
• EnvelopeGenerator.Web - Razor Pages (replaced by WebUI)
• VB.NET projects (Form, Service, BBTests) - Legacy, read-only for reference

Development Commands

Run Both Projects (Required)

# Terminal 1 - API Backend
cd EnvelopeGenerator.API
dotnet run

# Terminal 2 - Blazor Frontend
cd EnvelopeGenerator.WebUI\EnvelopeGenerator.WebUI
dotnet run

Critical: Both must run simultaneously. WebUI proxy forwards /api/* to API.

Build

dotnet build EnvelopeGenerator.sln

Project Boundaries

EnvelopeGenerator.Domain/          # Entities (Envelope, Receiver, Document, etc.)
EnvelopeGenerator.Application/     # MediatR CQRS (Commands, Queries, Handlers)
EnvelopeGenerator.Infrastructure/  # EF Core, SQL executors, repositories
EnvelopeGenerator.API/             # Controllers, endpoints
EnvelopeGenerator.WebUI/           # Server-side Blazor components
  ├─ Components/Pages/             # @rendermode InteractiveServer
EnvelopeGenerator.WebUI.Client/    # Client-side WASM components
  ├─ Pages/                        # @rendermode InteractiveWebAssembly
  ├─ Services/                     # HTTP API clients
  ├─ Models/                       # DTOs

Route Structure (Critical)

Route	File Location	Render Mode	Purpose
/	WebUI.Client/Pages/Index.razor	WASM	Landing page
/sender/login	WebUI.Client/Pages/LoginSenderPage.razor	WASM	Sender auth
/sender	WebUI.Client/Pages/EnvelopeSenderPage.razor	WASM	Sender dashboard
/envelope/login/{key}	WebUI.Client/Pages/LoginReceiverPage.razor	WASM	Receiver auth
/envelope/{key}	WebUI/Components/Pages/EnvelopeReceiverPage.razor	Server	PDF viewer + signing

Rule: PDF viewers MUST use @rendermode InteractiveServer (DevExpress backend requirement). Everything else uses WASM.

Coordinate System (CRITICAL)

Database stores INCHES (GdPicture14 native). Origin: top-left, Y-axis down.

Conversions

// Database (INCHES) → PDF Points
float points = inches * 72;

// Database (INCHES) → DevExpress DX
float dx = inches * 100;

// PDF.js Pixels → Database (INCHES)
float inches = (pixelX / canvasWidth) * pageWidthInches;

A4 Page: 8.27" wide × 11.69" tall = 595pt × 842pt

Signature Field Size: 1.77" × 1.96" (FIXED, do not change)

Evidence: See COPILOT_CONTEXT.md lines 158-185, EnvelopeGenerator.Form/frmFieldEditor.vb

API Architecture Quirks

Monolithic Endpoint (Avoid for UI)

POST /api/EnvelopeReceiver - Creates envelope+document+receivers+fields atomically.

• Use case: External API consumers
• Not suitable for: Step-by-step UI workflow (no draft support, no partial updates)

Missing Granular Endpoints (Need to Create)

POST /api/Envelope/draft          # Create draft envelope
PUT /api/Envelope/{id}            # Update metadata
DELETE /api/Envelope/{id}         # Delete with reason
POST /api/Envelope/{id}/document  # Upload PDF
POST /api/Envelope/{id}/receivers # Add receiver
POST /api/Envelope/{id}/signature-fields  # Place signature field
POST /api/Envelope/{id}/send      # Send to receivers

See FORM_APPLICATION_CONTEXT.md for detailed workflow requirements.

Status Color Coding

Form app uses DevExpress CustomDrawCell. WebUI needs CSS:

.envelope-row.status-partly-signed { background-color: #81C784; } /* GREEN_300 */
.envelope-row.status-queued,
.envelope-row.status-sent { background-color: #FFB74D; } /* ORANGE_300 */
.envelope-row.status-completed { background-color: #81C784; }
.envelope-row.status-deleted,
.envelope-row.status-rejected { background-color: #E57373; } /* RED_300 */

Configuration

YARP Proxy (WebUI/yarp.json)

Routes /api/*, /swagger/*, /openapi/*, /scalar/* → https://localhost:8088

PDF.js Settings (WebUI/wwwroot/appsettings.json)

{
  "PdfViewerOptions": {
    "ThumbnailBaseScale": 0.75,
    "ThumbnailEnableHiDPI": true,
    "MainCanvasEnableHiDPI": true,
    "ZoomStepPercentage": 5
  }
}

API Config (API/appsettings.json)

• ConnectionStrings:Default - SQL Server DB
• AllowedOrigins - CORS (includes http://localhost:5131, http://localhost:7192)
• Cache:SignatureCacheExpiration - Signature persistence timeout
• PSPDFKitLicenseKey - DEPRECATED (use PDF.js instead)

Migration Status

Complete ✅

• Receiver login/authentication
• PDF viewing with PDF.js (HiDPI, zoom, thumbnails)
• Signature capture (draw/type/image)
• Signature caching (Redis/SQL)
• Sender login

Missing (High Priority) ❌

• Sender dashboard (/sender) - Empty stub
• Envelope editor (/sender/envelope/{id})
• Signature field placement tool (PDF.js + draggable overlays)
• Granular API endpoints (draft, receivers, fields)
• Master-detail grids for receivers/history

Common Mistakes (DO NOT REPEAT)

Mistake	Why Wrong
Using iText7 in receiver pages	GPL license issue. Use PDF.js overlays.
Using PSPDFKit	Removed from architecture. Use PDF.js + DevExpress.
@rendermode InteractiveWebAssembly on PDF viewers	DevExpress DxPdfViewer requires server-side rendering.
Hardcoded quality in PDF.js	Use appsettings.json PdfViewerOptions.
Coordinates in points/pixels for DB	Database uses INCHES. Convert before save.
BottomMarginBand for signatures	Repeats on every page. Use DetailBand.

Testing

No automated tests exist yet.

Manual testing workflow:

1. Start API (dotnet run in EnvelopeGenerator.API)
2. Start WebUI (dotnet run in EnvelopeGenerator.WebUI\EnvelopeGenerator.WebUI)
3. Navigate to https://localhost:5131 (or check console output for port)
4. Test sender login at /sender/login
5. Test receiver flow at /envelope/login/{envelopeKey}

Database

SQL Server (DD_ECM)

• Connection string in API/appsettings.json
• EF Core migrations NOT used (manual SQL scripts)
• Stored procedures: PRSIG_* prefix

Key Tables:

• TBSIG_ENVELOPE - Envelope metadata
• TBSIG_ENVELOPE_RECEIVER - Receiver assignments
• TBSIG_DOC_RECEIVER_ELEMENT - Signature fields (X, Y in INCHES)
• TBSIG_RECEIVER - Receiver registry
• TBSIG_DOCUMENT - PDF binary data
• TBSIG_ENVELOPE_HISTORY - Audit trail

DevExpress

License: Commercial (v25.2.3) Components Used:

• DxGrid - Master-detail grids
• DxPdfViewer - Server-side PDF rendering
• DxPopup - Modal dialogs
• DxToolbar - Action bars
• DxFormLayout - Forms

Theme: Blazing Berry (default)

JavaScript Interop

PDF Viewer: wwwroot/js/pdf-viewer.js

window.pdfViewer = {
    initialize(canvasId, pdfDataUrl, dotNetRef),
    renderPage(num),
    renderSignatureButtons(signatures, pageNum, dotNetRef),
    applySignature(signatureId, dataUrl, fullName, position, place),
    zoomIn(), zoomOut(), dispose()
}

Signature Pad: wwwroot/js/receiver-signature.js

window.receiverSignature = {
    initializeDrawPad(canvasId, dotNetRef),
    getSignatureDataUrl(canvasId),
    clearPad(canvasId)
}

Multi-Envelope Support

Receivers can login to multiple envelopes simultaneously via per-envelope cookies:

AuthTokenSignFLOWReceiver.{envelopeKey}

Each envelope maintains independent authentication state.

External Dependencies

CDN:

• PDF.js 3.11.174: https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js

NuGet (WebUI.Client):

• DevExpress.Blazor.* 25.2.3
• SkiaSharp.* 3.119.1 (WASM rendering)

External Services:

• LDAP/AD authentication (optional)
• GTX Messaging (SMS 2FA)
• Email dispatcher (signFlow)

Environment Variables

None required. All config in appsettings.json.

Local dev ports:

• API: https://localhost:8088
• WebUI: https://localhost:5131 or http://localhost:7192