PDF generation with versioned Liquid templates.

SferaDoc combines:

• Storage: Templates in Ecto/ETS/Redis with automatic versioning
• Parsing: Liquid templates via solid (default, pluggable), cached in ETS
• Rendering: HTML to PDF via chromic_pdf (default, pluggable)
• Cache: Optional fast in-memory PDF cache (Redis/ETS)
• Object Store: Optional durable PDF storage (S3/Azure/FileSystem)

Quick Start

# 1. Configure storage
config :sfera_doc, :store,
  adapter: SferaDoc.Store.Ecto,
  repo: MyApp.Repo

# 2. Add migration
defmodule MyApp.Repo.Migrations.CreateSferaDocTemplates do
  use SferaDoc.Store.Ecto.Migration
end

# 3. Create template
{:ok, template} = SferaDoc.create_template(
  "invoice",
  "<h1>Invoice for {{ customer_name }}</h1><p>Amount: {{ amount }}</p>",
  variables_schema: %{"required" => ["customer_name", "amount"]}
)

# 4. Render to PDF
{:ok, pdf_binary} = SferaDoc.render("invoice", %{
  "customer_name" => "Acme Corp",
  "amount" => "$1,200.00"
})

File.write!("invoice.pdf", pdf_binary)

Storage Backends

Storage backends persist template source code and its metadata (name, version, variables_schema). This is separate from PDF storage templates are the input, PDFs are the output.

Two-Tier PDF Storage

SferaDoc uses a two-tier storage system for rendered PDFs:

1. Cache (fast, in-memory) - First lookup, short TTL
2. Object store (durable storage) - Second lookup, survives restarts

Cache

Fast in-memory cache. Supports Redis or ETS. Disabled by default.

# Redis (multi-node, production)
config :sfera_doc, :pdf_hot_cache,
  adapter: :redis,
  ttl: 60

# ETS (single-node, development)
config :sfera_doc, :pdf_hot_cache,
  adapter: :ets,
  ttl: 300

Override Redis connection (reuses :redis config by default):

config :sfera_doc, :pdf_hot_cache,
  adapter: :redis,
  ttl: 60,
  redis: [host: "cache.example.com", port: 6379]

Object Store

Durable storage for rendered PDFs. Available adapters:

Example S3 configuration:

config :sfera_doc, :pdf_object_store,
  adapter: SferaDoc.Pdf.ObjectStore.S3,
  bucket: "my-pdfs",
  region: "us-east-1"

For custom object store adapters, see Pluggable Engines below.

Versioning

Calling create_template/3 with the same name creates a new version. Previous versions are preserved.

iex> SferaDoc.create_template("template_name", "<h1>v1</h1>")
{:ok,
 %SferaDoc.Template{
   id: "c41ee418-e479-4751-8331-b55af0f8ef97",
   name: "template_name",
   body: "<h1>v1</h1>",
   version: 1,
   is_active: true,
   variables_schema: nil,
   inserted_at: ~U[2026-03-06 20:26:41Z],
   updated_at: ~U[2026-03-06 20:26:41Z]
 }}

iex> SferaDoc.create_template("template_name", "<h1>v2</h1>")
{:ok,
 %SferaDoc.Template{
   id: "942ba9af-a542-43e8-9b71-1313e2c551ef",
   name: "template_name",
   body: "<h1>v2</h1>",
   version: 2,
   is_active: true,
   variables_schema: nil,
   inserted_at: ~U[2026-03-06 20:28:25Z],
   updated_at: ~U[2026-03-06 20:28:25Z]
 }}

iex> SferaDoc.list_versions("template_name")
{:ok,
 [
   %SferaDoc.Template{
     id: "942ba9af-a542-43e8-9b71-1313e2c551ef",
     name: "template_name",
     body: "<h1>v2</h1>",
     version: 2,
     is_active: true,
     variables_schema: nil,
     inserted_at: ~U[2026-03-06 20:28:25Z],
     updated_at: ~U[2026-03-06 20:28:25Z]
   },
   %SferaDoc.Template{
     id: "c41ee418-e479-4751-8331-b55af0f8ef97",
     name: "template_name",
     body: "<h1>v1</h1>",
     version: 1,
     is_active: false,
     variables_schema: nil,
     inserted_at: ~U[2026-03-06 20:26:41Z],
     updated_at: ~U[2026-03-06 20:26:41Z]
   }
 ]}

iex> SferaDoc.activate_version("template_name", 1)  # rollback
{:ok,
 %SferaDoc.Template{
   id: "c41ee418-e479-4751-8331-b55af0f8ef97",
   name: "template_name",
   body: "<h1>v1</h1>",
   version: 1,
   is_active: true,
   variables_schema: nil,
   inserted_at: ~U[2026-03-06 20:26:41Z],
   updated_at: ~U[2026-03-06 20:31:45Z]
 }}

iex> SferaDoc.list_versions("template_name")
{:ok,
 [
   %SferaDoc.Template{
     id: "942ba9af-a542-43e8-9b71-1313e2c551ef",
     name: "template_name",
     body: "<h1>v2</h1>",
     version: 2,
     is_active: false,
     variables_schema: nil,
     inserted_at: ~U[2026-03-06 20:28:25Z],
     updated_at: ~U[2026-03-06 20:28:25Z]
   },
   %SferaDoc.Template{
     id: "c41ee418-e479-4751-8331-b55af0f8ef97",
     name: "template_name",
     body: "<h1>v1</h1>",
     version: 1,
     is_active: true,
     variables_schema: nil,
     inserted_at: ~U[2026-03-06 20:26:41Z],
     updated_at: ~U[2026-03-06 20:31:45Z]
   }
 ]}

Pluggable Engines

Storage backends, template engines, and PDF engines are all swappable via behavior adapters.

Storage Backend - Implement SferaDoc.Store.Adapter:

defmodule MyApp.MongoAdapter do
  @behaviour SferaDoc.Store.Adapter

  def worker_spec, do: nil  # Assuming Mongo supervised elsewhere

  def get(name), do: # Fetch active template by name
  def get_version(name, version), do: # Fetch specific version
  def put(template), do: # Insert/update with versioning
  def list(), do: # All templates (active only)
  def list_versions(name), do: # All versions for name
  def activate_version(name, version), do: # Make version active
  def delete(name), do: # Delete all versions
end

config :sfera_doc, :store,
  adapter: MyApp.MongoAdapter

Template Engine - Implement SferaDoc.TemplateEngine.Adapter:

defmodule MyApp.CustomTemplateEngine do
  @behaviour SferaDoc.TemplateEngine.Adapter

  def parse(template), do: {:ok, Mustache.compile(template)}
  def render(ast, vars), do: {:ok, Mustache.render(ast, vars)}
end

config :sfera_doc, :template_engine,
  adapter: MyApp.CustomTemplateEngine

PDF Engine - Implement SferaDoc.PdfEngine.Adapter:

defmodule MyApp.CustomPdfEngine do
  @behaviour SferaDoc.PdfEngine.Adapter

  def render(html, _opts) do
    # Shell out to WeasyPrint, wkhtmltopdf, etc.
    {:ok, pdf_binary}
  end
end

config :sfera_doc, :pdf_engine,
  adapter: MyApp.CustomPdfEngine

PDF Object Store - Implement SferaDoc.Pdf.ObjectStore.Adapter:

defmodule MyApp.GCSAdapter do
  @behaviour SferaDoc.Pdf.ObjectStore.Adapter

  def worker_spec, do: nil  # HTTP client, no supervision needed

  def get(name, version, hash) do
    # Fetch from Google Cloud Storage
    {:ok, pdf_binary}  # or :miss
  end

  def put(name, version, hash, binary) do
    # Upload to GCS
    :ok
  end
end

config :sfera_doc, :pdf_object_store,
  adapter: MyApp.GCSAdapter