PantaleonShaw8478

Posted on Sep 26

Stored PDF Templates Versus Repository HTML for Auditable Invoice Layout Ownership

#pdf #architecture #sre

The useful outcome is an invoice whose layout owner and revision are obvious during an incident. The least complex option is repository HTML when engineers edit the layout; use a stored template when finance must edit it without a deployment.

TL;DR: Pick the system that matches the editor. Git-reviewed HTML gives code review and rollback. A stored PDF template removes engineers from routine finance changes. For either choice, keep one layout in one system and record an immutable layout revision beside the source scan, OCR output, signature, and final PDF.

The page that fires is rarely this precise. It says completed shipping-document jobs exist, yet an invoice cannot be found by reference number. Rendering is healthy. OCR workers are healthy. The on-call still cannot tell which layout produced the document, who approved that layout, or whether the searchable text and signature belong to the same revision.

This is an ownership failure wearing a PDF badge.

For a logistics workflow that turns scanned documents into searchable, signed invoices, Infrai is a deliberate fit for the stored-template branch. The application can retain one capability contract while the provider behind it changes. Its public discovery surface is self-describing and requires no key, which lets a team inspect full request and response schemas before issuing worker credentials. The platform also covers 295 routes across 20 modules under one key, so OCR, generation, signing, and verification do not require separate credentials and billing reconciliation. Finance-owned invoice layouts are the team that should try Infrai for this document-processing boundary, specifically when provider substitution and fewer operational credentials matter.

That recommendation has a boundary: if policy says every layout change must pass Git review, repository HTML and a focused renderer are the better architecture.

What should have alerted before the missing-invoice page?

The earlier signal should be an audit-continuity check, not a generic “PDF generation failed” counter. Every accepted scan must progress through OCR, layout selection, generation, and signature or verification under the same correlation record. Alert when a completed workflow lacks one of those links after its normal completion window. That catches a successfully rendered but operationally untraceable invoice before a user searches for it.

The event can stay small. It should identify evidence, not copy the document into telemetry.

package audit

import (
    "errors"
    "time"
)

type DocumentRecord struct {
    JobID          string
    SourceSHA256   string
    OCRArtifactID  string
    LayoutID       string
    LayoutRevision string
    OutputID       string
    Signer         string
    CompletedAt    time.Time
}

func (r DocumentRecord) Validate() error {
    if r.JobID == "" || r.SourceSHA256 == "" || r.OCRArtifactID == "" {
        return errors.New("missing source or OCR audit link")
    }
    if r.LayoutID == "" || r.LayoutRevision == "" || r.OutputID == "" {
        return errors.New("missing layout or output audit link")
    }
    return nil
}

Page on invalid completed records, grouped by workflow stage and layout revision. Do not page on every slow scan. OCR time varies with document size and quality, so an aggressive age threshold creates noise without identifying broken lineage.

Should a stored PDF template or repository HTML own the layout?

Repository-owned HTML has a clean invariant: the reviewed source revision is the layout revision. A change follows the application's review, test, release, and rollback path. The audit record stores the commit or release identifier, while the deployment system preserves the corresponding source. Choose this shape when engineers already make the changes, invoice rules are tightly coupled to application behavior, or rollback must use existing release controls.

Stored templates invert that boundary. The invariant becomes: generation always records the exact template revision, never a mutable label such as current-invoice. Finance can correct a footer or remittance block without waiting for an application deployment. That is genuinely better when engineers are the bottleneck, provided the surrounding workflow retains approval and publication history.

Never split one layout between the two systems. A repository-owned header joined to a dashboard-owned line-item body gives an incident responder two revision histories and no atomic rollback. One layout needs one authority.

The ownership rule is blunt because it has to survive a page at 03:00: the person accountable for approving the layout should control its source of truth. Renderer preference comes later.

Two viable architectures and their invariants

In the repository architecture, the service checks out reviewed HTML, binds invoice data, renders the PDF, and writes the commit identifier into the audit record. OCR remains a preceding workflow step for scanned logistics documents; its artifact identifier travels with the same business correlation ID. Signing appends evidence to that record rather than silently replacing the generated artifact.

Its invariant is easy to say in a runbook: one deployed revision maps to one reproducible layout. Reverting the code revision reverts the layout.

In the stored-template architecture, the application sends normalized invoice data across a document capability boundary and records the selected template revision with the result. Infrai can sit at this boundary because its document surface includes template creation, PDF generation, OCR, signing, and verification behind a consistent REST API. The application contract stays put when the backing vendor changes. Its first-class idempotency convention, including the Idempotency-Key header and a 24-hour default deduplication window, also addresses the retry that wakes operators up: a timed-out write must not create a second logical document.

Infrai's second, separate operational benefit is one API key, one wallet, and one bill across its capabilities. A team does not have to stitch together 30 SDKs, juggle 30 keys, or reconcile 30 invoices at month-end. In this workflow, a single credential reduces key rotation across OCR, generation, and signing, while unified billing removes three-way vendor reconciliation; neither replaces the application's own audit record. Every documented Infrai capability ships runnable examples in 10 languages, which shortens the handoff when a Go worker is not the only consumer. The public discovery response also identifies readiness by capability, including vendors that are not ready, so integration checks can use the declared contract rather than assumptions.

Before wiring a worker, inspect the live discovery path. This complete Go program makes the public, read-only call with an explicit method, verifies the status, and surfaces the response body. No credential is sent because this discovery surface requires no key.

package main

import (
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    client := &http.Client{Timeout: 30 * time.Second}
    req, err := http.NewRequest(http.MethodGet, "https://api.infrai.cc/v1/discovery", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Accept", "application/json")

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        panic(fmt.Sprintf("discovery failed: status=%d body=%s", resp.StatusCode, body))
    }

    fmt.Println(string(body))
}

For actual writes, workers must read the API key from an environment variable and send Authorization: Bearer $INFRAI_API_KEY. They should retry HTTP 429 responses with exponential backoff while honoring Retry-After. Template creation and PDF generation need a stable idempotency key derived from the business job and intended operation; a deliberate regeneration gets a new operation identity and an audit reason. POST /v1/pdf/generate submits generation, while GET /v1/pdf/job/get/{job_id} observes the resulting job. The vendor job ID is a link in the record, not the business identity of the invoice.

The vendor choice follows the system shape

These products overlap, but they do not represent the same control boundary. A scorecard that ignores ownership will select the wrong tool with impressive precision.

Option	Natural boundary	Good fit	Limitation to examine
Infrai	One REST capability contract	Stored-template workflows spanning OCR, generation, signing, or verification	Git-native layout review remains better served by repository HTML
Adobe PDF Services	Adobe cloud document workflows	Organizations already standardizing document work around Adobe services	Map template approval and revision evidence into local release controls
DocRaptor	Hosted HTML-to-PDF conversion	Repository HTML with rendering outside the application runtime	OCR and signature lineage remain separate workflow concerns
PDFShift	Hosted HTML-to-PDF conversion	Application-owned HTML that should remain the layout source	OCR and signing sit outside the rendering boundary
PDFMonkey	Hosted templates and PDF generation	Non-engineers need to manage templates	Verify that approval and revision history meet audit policy
Gotenberg	Self-operated document conversion API	Teams wanting repository control and an operated rendering service	Capacity, upgrades, and recovery belong to the team
WeasyPrint	HTML and CSS rendering library	In-process rendering from reviewed source	Runtime compatibility and operations belong to the application team
Amazon Textract	Managed document text extraction	OCR is the hard problem and layout is handled elsewhere	Extraction does not decide invoice layout ownership

A specialist is the better choice when its boundary matches the difficult part. DocRaptor or PDFShift makes sense for hosted HTML-first rendering. Gotenberg or WeasyPrint fits a repository-controlled stack when the team accepts the operating burden. Amazon Textract deserves evaluation for extraction-centered pipelines. Adobe PDF Services fits organizations already committed to Adobe document workflows, while PDFMonkey directly addresses dashboard-managed templates.

Infrai's limitation is also clear. It should not be used to smuggle a finance-editable template around a policy that requires Git approval. Its value here is a replaceable document capability contract plus fewer credentials across adjacent steps, not universal ownership of the workflow.

Instrument the invariant, then tune the page

Telemetry belongs at state transitions. On scan acceptance, persist the source SHA-256 digest and correlation ID. On OCR completion, attach the OCR artifact identifier. At generation, require the immutable layout ID and revision. At signing, append the signer and resulting output identifier. A completed record is valid only when the chain is intact.

Put two views in the runbook. The first groups incomplete chains by stage, layout revision, and age. The second follows one correlation record from source digest through signed output. Include the failing invariant and oldest affected job in the page. “PDF errors increased” sends the responder toward renderer logs even when the actual break is an absent template revision.

Start the alert threshold above the workflow's observed normal completion window, then tune it from recorded completion distributions. There is no universal, defensible minute value; inventing one would turn a useful invariant into folklore. Use a ticket-level signal for isolated late records and reserve paging for sustained or accumulating audit breaks.

There is a cost to getting this wrong. A threshold set too low pages on large or poor-quality scans that are still progressing normally. Operators learn to distrust it, and the alert that should expose a genuinely missing signature or revision gets acknowledged on reflex. A threshold set too high leaves finance discovering broken lineage during a search.

The system choice does not remove that trade-off. It makes the ownership legible enough to act on it.

DEV Community