Architecture & C4
Inputs, rendering and data flow.
Explore the system in five views.
Architecture
Source inspection, rendering and model evaluation.
Reusable foundation crates
Arrows show crate dependencies. Foundations require no schema or Evidence. Core owns extraction output, aggregate timings/usage and field/page associations; PDF inspection has independent timings. Recording preserves every received attempt body before validation; logs contain no bodies, credentials or headers. Existing core API paths and default-off renderer features remain supported. Image-only PDFs can be inspected/rendered without OCR; extraction still requires source Evidence.
Click a box, or focus it with Tab and press Enter, to inspect its role and constraints.
Text inspection
Reads text and positions locally, independently of rendering.
Rendering
Renders page PNGs for Vision and Hybrid, preserving coordinate transforms.
Results and logs
Original responses are returned as data. Operational logs are separate and do not change results.
Show Mermaid model
flowchart LR
Files[PDF + schema] --> CLI[CLI]
Upload[Multipart PDF + schema + options] --> Server[Axum server]
Caller[Rust caller] --> Engine
CLI --> Engine[Extraction engine]
Server --> Engine
Engine --> Snapshot[pdf-probe: bounded PDF snapshot]
Snapshot --> Candidates[Source candidates + geometry]
Snapshot --> Renderer[pdf-render: optional PDFium / Hayro]
Candidates --> Plan[Dependency waves + compatible batches]
Renderer --> Plan
Plan --> Evaluator[Injected Evaluator]
Evaluator --> Fixture[Fixture evaluator]
Evaluator --> Remote[Remote evaluator]
Remote --> Admission[jev-client: limits + retries + recording]
Admission --> Jev[Jev HTTPS API]
Evaluator --> Resolve[Resolve + validate + provenance check]
Candidates --> Resolve
Resolve --> Report[Fields + Evidence + usage + jev_responses]
Remote --> Originals[Original attempt bodies]
Originals --> Report
Engine --> Logs[OpenTelemetry SDK logs]
Execution sequence
Question dependencies, request control and original responses.
Click a box, or focus it with Tab and press Enter, to inspect its role and constraints.
Before sending
Configure request rate, token rate, concurrency, context estimates and deadlines. Split questions to fit per-request and per-question estimates; reject an indivisible oversized question without truncating its source. Reserve the request estimate for every retry. The same limits apply to retries. Deadlines cannot forcibly interrupt a synchronous PDF parser or renderer call.
Retries
Uses capped exponential backoff with jitter and honors Retry-After. One to three attempts, including the initial request.
Concurrency and batches
Batches independent questions and executes them within configured concurrency and rate limits.
Show Mermaid model
sequenceDiagram
participant Adapter as CLI / HTTP / library caller
participant Engine
participant PDF as Snapshot / candidates / renderer
participant Eval as Evaluator
participant Control as Execution controller
participant API as Jev
Adapter->>Engine: PDF + validated schema + options
Engine->>PDF: Build snapshot; prepare scoped source/images
loop Dependency waves
Engine->>Eval: Compatible independent question batches
loop Each attempt within configured bounds
Eval->>Control: Reserve request/tokens/cost; await admission
Control-->>Eval: Permit or bounded failure
Eval->>API: HTTPS request
API-->>Eval: HTTP status + original body
Eval->>Eval: Retain original body before validation
opt Retryable and budget/deadline allows
Eval->>Control: Wait exponential backoff + jitter / Retry-After
end
end
Eval-->>Engine: Answers/errors + usage + original responses
Engine->>Engine: Resolve source, validate, check provenance
end
Engine-->>Adapter: Partial report or error with received responses
C4 · System context
Users, external systems and data boundaries.
Click a box, or focus it with Tab and press Enter, to inspect its role and constraints.
Input boundary
Accepts a PDF and a user-defined extraction schema.
Remote boundary
Sends scoped text or PNG images and questions to Jev. The PDF file itself is not uploaded.
Output boundary
Callers control storage and access to results, which contain source text, coordinates and response data.
Show Mermaid model
C4Context
title VOLTFILL system context
Person(user, "User / application developer", "Defines questions and reviews source-backed values")
System(voltfill, "VOLTFILL", "Extracts structured values and Evidence from PDFs")
System_Ext(jev, "Jev API", "Evaluates declared text/image questions")
System_Ext(consumer, "Consuming application", "Reviews results and owns downstream actions")
Rel(user, voltfill, "Supplies PDF, schema and explicit execution permissions")
Rel(voltfill, jev, "Sends scoped text/images and questions when enabled", "HTTPS")
Rel(voltfill, consumer, "Returns evaluation-only fields, Evidence, usage and original responses", "JSON / Rust values")
C4 · Containers
Executable processes and external connections.
Click a box, or focus it with Tab and press Enter, to inspect its role and constraints.
Launch and configuration
Both run and serve use the shared core, applying startup settings to PDF/render resource limits and Jev execution control. PDFium and Hayro are optional features; PDFium requires an explicit library path. See Launch configuration guide for settings and precedence.
HTTP admission
Uploads allow 16 MiB PDF, 1 MiB schema and 64 KiB options, with a 30-second upload deadline. Busy requests receive 429.
Deployment boundary
Binds to loopback by default. Non-loopback binding and extraction requests with an Origin header require Bearer authentication. A remote server must be started with --allow-images to accept image-based extraction. Deployments provide TLS ingress and parser isolation.
Show Mermaid model
C4Container
title VOLTFILL runtime containers
Person(user, "Caller", "Local user or HTTP client")
System_Boundary(voltfill, "VOLTFILL") {
Container(cli, "voltfill run", "Rust executable", "Validates files/options, invokes core and emits JSON")
Container(server, "voltfill serve", "Rust / Axum / Tokio", "Authenticates multipart uploads and admits bounded jobs")
}
System_Ext(jev, "Jev API", "Configured HTTPS model endpoint")
System_Ext(sink, "Log writer / optional collector", "Disabled by default; local OTLP JSONL when enabled; caller-configured SDK exporter for forwarding")
Rel(user, cli, "Provides PDF/schema files and flags")
Rel(user, server, "Uploads PDF/schema/options", "HTTP multipart; Bearer when required")
Rel(cli, jev, "Evaluates batches through linked core", "HTTPS")
Rel(server, jev, "Evaluates batches through linked core / blocking worker", "HTTPS")
Rel(cli, sink, "Emits structured events", "OpenTelemetry SDK")
Rel(server, sink, "Emits structured events", "OpenTelemetry SDK")
C4 · Components
Responsibilities and result flow across the shared core and foundation crates.
Click a box, or focus it with Tab and press Enter, to inspect its role and constraints.
Source correspondence
Preserves original text separately from normalized values. Positions distinguish identical strings. Partial scope cannot establish document-wide absence.
Response retention
Returns received UTF-8 bodies as original strings and other bodies as bytes, including retries and validation failures. Receive failures and limits are explicit; body_complete is false for incomplete bodies or attempts without a received body.
Requirements
Requires usable text and coordinates. PDFs whose character mappings differ from visible glyphs may not be supported.
Show Mermaid model
C4Component
title Voltfill linked crates and components
Container_Boundary(host, "CLI or HTTP server process") {
Component(adapter, "Host adapter", "CLI / Axum", "Supplies inputs, options and evaluator")
Component(schema, "Schema", "schema", "Validates fields, dependencies, modalities and resolver rules")
Component(engine, "Engine", "engine", "Schedules dependency waves and compatible independent batches")
Component(pdf, "PDF snapshot", "pdf-probe", "Bounds source inspection and validates page metadata")
Component(source, "Source index", "core::candidates + probe::geometry", "Tracks original runs, coordinates and canonical Evidence")
Component(render, "Renderer", "pdf-render features", "Produces bounded PNGs and transform ledgers")
Component(eval, "Evaluator", "evaluate", "Fixture or remote question evaluation")
Component(transport, "Execution and HTTP", "jev-client", "Applies configured limits, concurrency and retries")
Component(validation, "Resolution and validation", "engine + validate", "Checks source, mappings, acceptance and provenance")
Component(model, "Result model", "model", "Partial field results, Evidence, usage and original response bodies")
Component(logging, "Telemetry logger", "logging over otel-log", "Compatibility layer; otel-log writes the OTLP JSONL output")
}
System_Ext(jev, "Jev API", "Text/image evaluation")
Rel(adapter, schema, "Parses form")
Rel(adapter, engine, "Calls extraction")
Rel(engine, pdf, "Inspects PDF")
Rel(pdf, source, "Provides source runs")
Rel(engine, render, "Requests scoped page images")
Rel(engine, eval, "Evaluates batches")
Rel(eval, transport, "Requests bounded remote execution")
Rel(transport, jev, "Sends explicit requests", "HTTPS")
Rel(eval, validation, "Provides answers and usage")
Rel(source, validation, "Supplies canonical source Evidence")
Rel(validation, model, "Constructs field results")
Rel(transport, model, "Retains each original received body")
Rel(engine, logging, "Emits counts, statuses and durations")