Architecture & C4

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]

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

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")

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")

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")