PdfForge.Core 1.1.0

PDF Forge - Enterprise PDF Generation Engine

Proprietary Closed-Source Software
30-day free trial + Perpetual licensing model.
See LICENSE.md and SUPPORT.md for licensing details.

A high-performance, multi-tenant PDF generation engine for enterprise SaaS platforms. Built with .NET 10.0+, designed for scale, security, and extensibility.

---

Table of Contents

• About
• Features
• Tech Stack
• Architecture
• Project Structure
• Getting Started
• Configuration
• Security
• How to Contribute
• GitHub Actions & CI/CD
• Release Notes
• What's Next
• License
• Acknowledgements
• Author

---

About

PDF Forge solves the challenge of generating high-quality PDFs in enterprise SaaS environments where:

• Multi-tenancy is critical for data isolation and compliance
• Performance directly impacts user experience (sub-second PDF generation)
• Security is non-negotiable (decompression bombs, injection attacks, timing attacks)
• Reliability means 99.9%+ uptime with comprehensive testing

The engine converts multiple formats (HTML, Word, Excel, images, text) into production-grade PDFs while maintaining strict tenant boundaries and security standards.

Where it fits:

• SaaS platforms requiring PDF generation
• Enterprise document management systems
• Automated reporting pipelines
• Batch processing workflows with webhooks

---

Features

Core Capabilities

• ✅ HTML to PDF - Render complex web layouts
• ✅ Word (DOCX) to PDF - Preserve formatting and styles
• ✅ Excel (XLSX) to PDF - Multi-sheet support with optional horizontal pagination
• ✅ Image to PDF - With bounds checking
• ✅ Text to PDF - Simple text rendering
• ✅ Template Rendering - Reusable document templates
• ✅ Batch Processing - High-volume document generation
• ✅ Webhooks - Job completion notifications

Enterprise Features

• 🔐 Multi-Tenant Isolation - AsyncLocal ambient context, thread-safe
• ⚡ High Performance - Object pooling, caching, async/await
• 🛡️ Security Hardening - JPEG bomb prevention, key rotation, constant-time validation
• 📊 Observability - Correlation IDs for distributed tracing
• 🧪 Comprehensive Testing - 952+ unit tests (100% passing)
• 📈 Scalability - Horizontal scaling ready

---

Tech Stack

Layer	Technology
Runtime	.NET 10.0+
Framework	ASP.NET Core (if applicable)
DI Container	Microsoft.Extensions.DependencyInjection
Testing	xUnit, custom test framework
Logging	Custom IEventLogger interface
Threading	AsyncLocal<T>, ConcurrentDictionary, ReaderWriterLockSlim
Performance	Custom object pooling, LRU caching
Security	Cryptographic hash validation, input sanitization

Dependency-Free Core: No external PDF libraries—pure .NET implementation for maximum control and security.

---

Architecture

High-Level Design

┌─────────────────────────────────────────────────────────────┐
│                    API Layer (REST/gRPC)                     │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│ │ TenantScope  │  │ CorrelationID│  │ ResourceLimits   │   │
│ │ (Context)    │  │ (Tracing)    │  │ (DoS Protection) │   │
│ └──────────────┘  └──────────────┘  └──────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│ ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│ │ HTML       │  │ Word       │  │ Excel      │  ...        │
│ │ Converter  │  │ Converter  │  │ Converter  │             │
│ └────────────┘  └────────────┘  └────────────┘             │
├─────────────────────────────────────────────────────────────┤
│ ┌────────────────┐  ┌────────────┐  ┌────────────┐         │
│ │ Font Manager   │  │ Layout     │  │ Graphics   │         │
│ │                │  │ Engine     │  │ Renderer   │         │
│ └────────────────┘  └────────────┘  └────────────┘         │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐  ┌──────────────┐  ┌────────────┐     │
│ │ MemoryStreamPool │  │ CssCache     │  │ TextLayout │     │
│ │ (Performance)    │  │ (Performance)│  │ Cache      │     │
│ └──────────────────┘  └──────────────┘  └────────────┘     │
├─────────────────────────────────────────────────────────────┤
│           PDF Writer & Storage Layer                         │
└─────────────────────────────────────────────────────────────┘

Design Patterns

• Multi-Tenant: AsyncLocal<T> for ambient context isolation
• Performance: Object pooling + LRU caching at hot paths
• Security: Layered validation (input sanitization, bounds checking, rate limiting)
• Observability: Correlation IDs flowing through async call chains
• Extensibility: Plugin architecture with interfaces

---

Project Structure

pdf-forge/
│
├── README.md                           # This file
├── ROADMAP.md                          # Product roadmap
│
├── src/                                # Source code
│   ├── Logging/                        # Logging framework
│   │   ├── IEventLogger.cs            # Interface
│   │   ├── ConsoleEventLogger.cs      # Implementation
│   │   └── CorrelationContext.cs      # Distributed tracing
│   │
│   ├── DependencyInjection/           # DI configuration
│   │   ├── PdfForgeServiceCollectionExtensions.cs
│   │   └── ServiceCollectionExtensions.cs
│   │
│   ├── Pdf/                           # PDF core
│   │   ├── PdfDocument.cs            # Main API
│   │   └── MemoryStreamPool.cs       # Performance optimization
│   │
│   ├── Css/                          # CSS processing
│   │   └── CssSelectorCache.cs      # Caching layer
│   │
│   ├── Layout/                       # Text layout
│   │   └── TextLayoutCache.cs       # Caching layer
│   │
│   ├── Security/                     # Security components
│   │   ├── ResourceLimitEnforcer.cs
│   │   ├── InputSanitizer.cs
│   │   └── LocalFileStorageProvider.cs (key rotation)
│   │
│   ├── Fonts/                        # Font engine
│   ├── Images/                       # Image processing
│   ├── Templates/                    # Template system
│   ├── Html/                         # HTML parsing
│   ├── Batch/                        # Batch processing
│   └── TenantScope.cs               # Multi-tenant context
│
├── tests/                             # 952 unit tests
│   ├── PerformanceOptimizationTests.cs (Phase 6)
│   ├── SecurityValidationTests.cs
│   ├── TenantIsolationTests.cs
│   └── ... (30 test files)
│
├── benchmarks/                        # Performance benchmarks
│   ├── Program.cs
│   └── BenchmarkRunner.cs
│
├── docs/                              # Reference documentation
│   ├── START_HERE.md                 # Setup guide
│   ├── SECURITY-AUDIT-REPORT.md      # Audit results
│   ├── 01-architecture.md            # Detailed architecture
│   ├── 05-coding-standards.md        # Code style
│   ├── 07-testing-strategy.md        # Testing approach
│   └── ... (36 reference docs)
│
├── global.json                        # .NET version constraints
├── Directory.Build.props              # Build configuration
└── PdfForge.sln                      # Solution file

---

Getting Started

HTML + Barcode Batch Sample

A runnable sample project is available at samples/HtmlBarcodeBatchSample that demonstrates:

• 4-page HTML template rendering per record
• Template token replacement (name, address, date, contact, and more)
• Top-right barcode rendering on each page
• Single-record PDF generation
• Batch generation for 55 records
• Individual PDF output per record
• Final merged PDF containing all batch records

Run it with:

dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj

Generated files are written under:

• samples/HtmlBarcodeBatchSample/bin/Debug/net10.0/output/single
• samples/HtmlBarcodeBatchSample/bin/Debug/net10.0/output/batch/individual
• samples/HtmlBarcodeBatchSample/bin/Debug/net10.0/output/batch/batch-all-records.pdf

NuGet Package Validation Sample

Another runnable sample is available at samples/NuGetPackageValidationSample to validate consuming PdfForge as a NuGet package (v1.1.0) instead of a project reference.

Before running the sample locally, ensure nupkg-local contains PdfForge.Core.1.1.0.nupkg (or publish 1.1.0 to NuGet.org) so restore can resolve the package.

Run it with:

dotnet run --project samples/NuGetPackageValidationSample/NuGetPackageValidationSample.csproj

Generated files are written under:

• samples/NuGetPackageValidationSample/bin/Debug/net10.0/output/text-to-pdf.pdf
• samples/NuGetPackageValidationSample/bin/Debug/net10.0/output/html-to-pdf.pdf
• samples/NuGetPackageValidationSample/bin/Debug/net10.0/output/word-to-pdf.pdf
• samples/NuGetPackageValidationSample/bin/Debug/net10.0/output/excel-to-pdf.pdf
• samples/NuGetPackageValidationSample/bin/Debug/net10.0/output/image-to-pdf.pdf

Sample Commands

Run format-specific samples from the same project:

# HTML + barcode batch sample (default)
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj

# Programmatic Word model -> PDF sample
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --word-test

# Parse .docx -> PDF sample
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --docx-test

# Parse .xlsx -> PDF sample (stress case)
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --excel-test

# NuGet package consumption validation sample
dotnet run --project samples/NuGetPackageValidationSample/NuGetPackageValidationSample.csproj

Excel sample outputs are written under:

• samples/HtmlBarcodeBatchSample/bin/Debug/net10.0/output/excel/sample-input.xlsx
• samples/HtmlBarcodeBatchSample/bin/Debug/net10.0/output/excel/excel-sample.pdf

Recent Updates

• HTML <img> tag rendering support in src/Html/HtmlRenderer.cs and src/Html/HtmlParser.cs
• Image overlay/header-footer options in src/Images/ImageOverlayOptions.cs
• Word rendering options in src/Word/WordRendererOptions.cs
• Batch watermark and writer integration hardening in src/Batch/BatchEngine.cs and src/Pdf/Writing/PdfWriter.cs
• Additional input sanitization/security validation hardening in src/Security/InputSanitizer.cs and src/Security/SecurityValidator.cs
• DOCX rendering improvements in src/Word/WordRenderer.cs:
  • Better paragraph spacing defaults
  • More stable line placement for wrapped content
  • Improved symbol fallback handling in text streams
• HTML/PDF text symbol handling improvements in src/Pdf/Content/PdfContentStreamBuilder.cs:
  • Better fallback encoding for common symbols in standard PDF fonts
• Excel horizontal pagination options in src/Excel/ExcelRenderer.cs:
  • EnableHorizontalPagination
  • RepeatHeaderRowOnEachPage
  • PreferredColumnWidth
  • FixedColumnsPerPage

Prerequisites

# Verify .NET version
dotnet --version
# Expected: 10.0.0 or higher

• .NET 10.0+ SDK
• Visual Studio 2024+, VS Code, or Rider
• Git for version control

Installation

# 1. Clone repository
git clone https://github.com/DNVerma88/pdf-forge.git
cd pdf-forge

# 2. Verify setup
dotnet --version
dotnet --list-sdks

# 3. Build solution
dotnet build

# 4. Run tests (verify everything works)
dotnet run --project tests/
# Expected output: Tests run: 952, Passed: 952, Failed: 0

# 5. Run benchmarks (optional)
dotnet run --project benchmarks/ --configuration Release

First PDF Generation

using PdfForge;
using PdfForge.Logging;

// 1. Setup DI
var services = new ServiceCollection();
services.AddPdfForge(new PdfForgeOptions 
{ 
    StorageRootPath = "/tmp/pdfs" 
});
var provider = services.BuildServiceProvider();

// 2. Create document
var doc = provider.GetRequiredService<PdfDocument>();
var page = new PdfPage(PdfRectangle.Letter);
doc.AddPage(page);

// 3. Write PDF
await doc.WriteToFileAsync("output.pdf", CancellationToken.None);

Console.WriteLine("✅ PDF generated: output.pdf");

---

Configuration

Environment Variables

# Storage configuration
PDFFORGE_STORAGE_PATH=/data/pdfs
PDFFORGE_CACHE_SIZE=1000

# Logging
PDFFORGE_LOG_LEVEL=Information
PDFFORGE_ENABLE_TRACING=true

# Performance
PDFFORGE_POOL_MIN_SIZE=4
PDFFORGE_POOL_MAX_SIZE=64
PDFFORGE_CACHE_ENTRIES=1000

Startup Configuration

var options = new PdfForgeOptions
{
    StorageRootPath = Environment.GetEnvironmentVariable("PDFFORGE_STORAGE_PATH"),
    MaxCacheSize = int.Parse(
        Environment.GetEnvironmentVariable("PDFFORGE_CACHE_SIZE") ?? "1000"
    )
};

services.AddPdfForge(options);

Resource Limits

// Per-tenant configuration
var limits = JobResourceLimits.CreateForProfessionalTier(
    maxOutputPages: 1000,
    maxJobDuration: TimeSpan.FromMinutes(5),
    maxMemory: 512 * 1024 * 1024  // 512 MB
);

services.AddSingleton(limits);

---

Security

Built-In Protections

Threat	Mitigation
Decompression Bombs	JPEG bounds checking (50MB max, 16384px, 256MP)
Timing Attacks	Constant-time signature comparison
Key Compromise	PresignKey rotation (hourly schedule + 5-min grace)
XSS Injection	HTML input sanitization
Tenant Breach	AsyncLocal<T> isolation + validation
DoS Attacks	Resource limits (pages, duration, memory)

Security Best Practices

1. Secrets Management

   // Use secure configuration, not hardcoded keys
   var apiKey = configuration["Security:ApiKey"];  // From env/vault
   

2. Input Validation

   var sanitized = InputSanitizer.SanitizeHtml(userInput);
   

3. Tenant Isolation

   using (new TenantScope(tenantContext))
   {
       // All operations automatically isolated
   }
   

4. Audit Logging

   logger.LogInformation(
       "PDF generated for tenant {TenantId}: {DocumentId}",
       tenantId, documentId
   );
   

Compliance

• ✅ OWASP Top 10 considerations implemented
• ✅ Audit logging for all operations
• ✅ Data isolation for multi-tenant compliance
• ✅ Current controls and remediation status: docs/SECURITY-IMPLEMENTATION.md
• ✅ Historical audit baseline and findings: docs/SECURITY-AUDIT-REPORT.md

---

How to Contribute

Git Flow

# 1. Create feature branch
git checkout -b feature/your-feature-name

# 2. Make changes (with tests!)
# 3. Ensure tests pass
dotnet run --project tests/

# 4. Commit with clear message
git commit -m "feat: add feature description"

# 5. Push and create PR
git push origin feature/your-feature-name

Coding Standards

• Follow docs/05-coding-standards.md
• All public methods must have XML documentation
• Maintain async/await patterns (no sync-over-async)
• Use dependency injection via constructor
• Thread safety: Use AsyncLocal<T> for ambient context

Before Submitting PR

# 1. Build solution
dotnet build

# 2. Run all tests (must pass)
dotnet run --project tests/

# 3. Check code coverage
dotnet test --collect:"XPlat Code Coverage"

# 4. Run linter/formatter
# (Configure in your IDE or use:)
dotnet format

Test Requirements

• New features must include unit tests
• Bug fixes must include regression tests
• Minimum coverage: 80% of new code
• Performance-critical: Include performance tests

---

GitHub Actions & CI/CD

Automated Workflows

Two separate, independent workflows automate build, test, and publishing:

1. CI - Build & Test (.github/workflows/ci.yml)

Runs automatically on:

• ✅ Push to main or release/** branches
• ✅ Pull requests to main
• ✅ Manual trigger via GitHub Actions

Steps:

1. Checkout code
2. Setup .NET 10.0
3. Restore dependencies
4. Build (Release config)
5. Run 952 unit tests ← Must pass!
6. Create NuGet package
7. Upload artifacts

2. CD - Publish to NuGet (.github/workflows/cd.yml)

Runs manually or on release:

• ✅ Manual trigger with required package_version input
• ✅ Automatic on GitHub release published

Steps:

1. Checkout code
2. Setup .NET 10.0
3. Resolve package version from release tag or package_version
4. Create NuGet package
5. Validate README metadata and ensure version is new on NuGet
6. Publish to NuGet.org

Manual Workflow Triggers

Run CI workflow:

GitHub.com/DNVerma88/pdf-forge
  ↓ Actions tab
  ↓ CI - Build & Test
  ↓ Run workflow

Run CD workflow (Publish):

GitHub.com/DNVerma88/pdf-forge
  ↓ Actions tab
  ↓ CD - Publish to NuGet
  ↓ Run workflow → package_version: 1.1.0

For detailed workflow reference, see WORKFLOWS_REFERENCE.md

---

Release Notes

v1.1.0 (June 22, 2026)

• Added HTML <img> tag rendering support for inline and referenced images.
• Added image overlay options for header/footer and branded compositing scenarios.
• Added WordRendererOptions for customizable margins, page size, and typography defaults.
• Hardened input sanitization and security validation paths.
• Improved batch/watermark integration in writer and scheduler flow.
• Expanded automated coverage to 952 passing tests.

For detailed release history, see CHANGELOG.md.

---

What's Next

Upcoming (Q3 2026)

• Advanced font subsetting
• Enhanced image optimization
• Plugin framework v2
• GraphQL API support

Roadmap

See ROADMAP.md for detailed product roadmap and timelines.

Known Limitations

• Maximum document size: 10GB (design constraint)
• Concurrent jobs per tenant: 100 (configurable)

---

📋 Licensing

PdfForge is proprietary closed-source software with a commercial licensing model:

30-Day Free Trial

• ✅ All features enabled
• ✅ No watermark
• ✅ No credit card required
• 📍 Watermark appears after day 30 (unless licensed)

Perpetual License

• ✅ Valid forever (no renewal)
• ✅ One-time payment
• ✅ All features included
• ✅ Commercial use allowed

Purchase: Email deepnverma87@gmail.com
Questions: See SUPPORT.md

---

License

Proprietary Commercial License - See LICENSE file for full legal terms.

This software is NOT open source. Source code is proprietary and not publicly available.

Key terms:

• ✅ Use PdfForge.Core NuGet package in your projects (with valid license)
• ✅ Distribute applications that use PdfForge
• ❌ Cannot modify, reverse-engineer, or access source code
• ❌ Cannot redistribute NuGet binaries without a valid license

For licensing inquiries: LICENSE.md and SUPPORT.md

---

Acknowledgements

This project builds on best practices from:

• Microsoft - .NET Framework and standard libraries
• OWASP - Security guidelines and threat modeling
• The .NET Community - Async/await patterns and conventions
• Enterprise Architecture - Multi-tenant and performance patterns

Special thanks to the security researchers and contributors who've helped identify and resolve vulnerabilities.

---

Author

PDF Forge

• 📧 Email: deepnverma87@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: docs/START_HERE.md
• 🔐 Security Concerns: Report privately to deepnverma87@gmail.com

Author: Deep Narayan Verma
Organization: DNVerma88
Last Updated: June 22, 2026
Status: Production Ready ✅

---

Questions? Start with docs/START_HERE.md or check ROADMAP.md.

• OMR / Barcode
• Batch Processing
• Streaming Merge
• Security & Compliance
• Multi-Tenant Licensing
• High Performance Rendering

Recommended Architecture: Core → Rendering → Format Engines → Batch → Security → Compliance