Architecture & Data Flow

Hosting Model

VaultPDF uses a customer-owned infrastructure model. Every component that processes or stores your documents deploys into your own Azure subscription using the supplied Bicep templates. VaultPDF does not operate a shared multi-tenant processing environment.

The only two VaultPDF-operated services are:

• Licensing API - validates your license key; receives license key and tenant ID only
• eSign Portal - stateless redirect endpoint; verifies a short-lived token; stores no document data

Architecture Diagram

For the canonical architecture diagram and interactive Mermaid source, see the System Architecture page: System Architecture.

Trust Boundaries

For a canonical diagram and Mermaid source view, see the System Architecture page: System Architecture.

Licensing Architecture (Tiered Cache Model)

VaultPDF uses a 4-tier license validation cascade to minimise runtime dependency on the VaultPDF Licensing API.

Nightly Sync

sequenceDiagram
  participant Timer as Nightly Timer
  participant Dispatcher as The Dispatcher
  participant LicAPI as VaultPDF Licensing API
  participant SP as SharePoint license.vpdf

  Timer->>Dispatcher: Trigger scheduled sync
  Dispatcher->>LicAPI: Validate licenseKey and tenantId
  LicAPI-->>Dispatcher: Return signed entitlement object
  Dispatcher->>SP: Write signed license.vpdf
  Dispatcher->>LicAPI: Push usage counts only

Runtime Tier Cascade

flowchart TD
    R["Runtime license check"] --> T1{"Tier 1\nIn-memory cache\n(24 h TTL)"}
    T1 -->|"Valid"| Allow1["✅ Allowed\n(no API call)"]
    T1 -->|"Expired / empty"| T2{"Tier 2\nSharePoint license.vpdf\n(JWS ES256 signed)"}
    T2 -->|"Valid — non-trial"| Allow2["✅ Allowed\n(no API call)"]
    T2 -->|"Missing / expired / trial"| T3{"Tier 3\nVaultPDF Licensing API"}
    T3 -->|"Valid"| Allow3["✅ Allowed\n(cache refreshed)"]
    T3 -->|"Invalid (revoked / expired)"| Deny["❌ Denied"]
    T3 -->|"Unreachable"| T4{"Tier 4\n48 h grace\n(API unavailable only)"}
    T4 -->|"Within 48 h of last valid"| Allow4["✅ Allowed\n(last known good)"]
    T4 -->|"Grace expired"| Deny2["❌ Denied"]

Failure Isolation

Runtime Principle

The Licensing API is not called on every request. With a populated Tier 1 cache, API calls occur at most once per 24 hours. With a valid SharePoint license.vpdf, API calls occur only if the in-memory cache is empty — typically only after a function cold start.

Sequence Diagram - Render Request (Data Residency View)

This sequence diagram shows the full render request path step by step. For AppSource and ISV review: note that document content never crosses into VaultPDF-operated infrastructure.

sequenceDiagram
    actor User as 👤 User (SharePoint)
    participant SPFx as SPFx App<br/>(Microsoft 365 tenant)
    participant SPO as SharePoint Online<br/>(Microsoft 365 tenant)
    participant Dispatcher as The Dispatcher<br/>func-dispatcher<br/>(your Azure subscription)
    participant LicAPI as VaultPDF Licensing API<br/>(VaultPDF-operated)
    participant SB as Azure Service Bus queues<br/>(your Azure subscription)
    participant KV as Azure Key Vault<br/>(your Azure subscription)
    participant Processor as The Vault Engine<br/>func-processor<br/>(your Azure subscription)
    participant Storage as Azure Blob Storage<br/>(your Azure subscription)

    User->>SPFx: Click "Generate PDF" (SPFx path)
    Note over User,Dispatcher: Source systems may also POST /api/render directly to the Dispatcher, skipping SPFx
    SPFx->>Dispatcher: POST /api/render (Function Key · HTTPS)

    Dispatcher->>SPO: Read template + payload (Graph API · MSI)
    SPO-->>Dispatcher: template + payload data

    Dispatcher->>LicAPI: Validate license
    Note over Dispatcher,LicAPI: Body: { licenseKey, tenantId }<br/>❌ No document content crosses this boundary
    LicAPI-->>Dispatcher: { features: { ... } }

    Dispatcher->>KV: Get encryption keys (MSI)
    KV-->>Dispatcher: Keys
    Dispatcher->>SB: Enqueue render message (MSI)

    SB->>Processor: Dequeue render message (MSI trigger)
    Processor->>SPO: Read template (Graph API · MSI)
    SPO-->>Processor: Template data
    Processor->>KV: Get keys (MSI)
    KV-->>Processor: Keys
    Processor->>Processor: Render PDF in memory (Ephemeral Processing Unit)
    Processor->>SPO: Upload PDF to output library (Graph API · MSI)
    Processor->>Storage: Write audit JSONL event (MSI)
    Processor->>SPO: Update Activity list (Graph API · MSI)
    SPFx-->>User: Document ready notification

Trust Boundaries - Summary View

A simplified view of who controls what, for procurement and legal review.

graph LR
      subgraph CustomerEnv["🔒 Customer Environment"]
          SP["SharePoint Libraries<br/>Document data · Activity lists"]
          EID["Entra ID<br/>Authentication · MSI trust"]
          Disp["The Dispatcher<br/>func-dispatcher"]
          Proc["The Vault Engine<br/>func-processor"]
          SB2["Azure Service Bus queues"]
          KV2["Azure Key Vault<br/>All encryption keys"]
          Stor["Azure Blob Storage<br/>Outputs · Audit JSONL"]
          AI2["App Insights<br/>(no document content)"]
      end

      subgraph VaultPDFBoundary["🏢 Vault Platform Shared Services"]
          LicAPI2["Licensing API<br/>Receives: license key + tenant ID only"]
          NOTIFY2["VaultNotification API<br/>Receives: notification metadata only"]
          ACS2["Azure Communication Services<br/>Email · SMS (VaultPDF or BYO)"]
          eSign2["eSign Portal<br/>Receives: HMAC token only · stateless relay"]
          NOTIFY2 --> ACS2
      end

      Disp -->|"license key + tenant ID — no document content"| LicAPI2
      Disp -.->|"HMAC token redirect — no document bytes"| eSign2
      eSign2 -.->|"token verify"| Disp
      Proc -.-> NOTIFY2
      NOTIFY2 -.-> Proc

Data Flow - eSign Request

Approver clicks eSign link in email
  → Browser loads VaultPDF eSign Portal (HTTPS redirect)
    → Portal verifies portal token with The Dispatcher (HTTPS, token only)
    → The Dispatcher validates token, returns approver context
    → Portal redirects browser back to Dispatcher endpoint
      → The Dispatcher renders signing page (served from your Azure Function)
      → Approver signs
      → The Dispatcher records approval, enqueues seal message
        → The Vault Engine seals document, writes .vpdf archive to your Azure Blob Storage

The eSign Portal acts as a stateless relay - it holds no document data. The signing page is served directly from your Dispatcher function.

Key Management

All encryption keys are stored in your Azure Key Vault. VaultPDF uses:

VaultPDF vendor staff have no access to your Azure Key Vault. Key rotation is an operator action performed by your team using az keyvault secret set or the Azure Key Vault portal.

Network Controls

All four Azure Storage accounts (stDisp, stProc, stData, stOut) have networkAcls.defaultAction: Deny with bypass: AzureServices. External internet access to storage is blocked at the network ACL layer. Function App MSI access traverses the Azure backbone.

VaultPDF's outbound calls to the Licensing API and eSign Portal use HTTPS/TLS 1.2+. No inbound firewall rules need to be opened for these calls.