DEV Community: bitavu

Your AI agent built PDF export but who owns the next change

bitavu — Tue, 03 Nov 2026 23:50:27 +0000

Imagine asking your coding agent to add a client report export.

It creates a route, adds a button, connects the data, and produces a tidy PDF.

The agent says done.

Then another team sends a message:

"Looks great. Could we add a column, use the new font, and make six client versions?"

Your agent can write another patch. You can ask it again next week.

But there is a question hiding behind all that generated code:

Who owns the report after the agent finishes the feature?

I'm building Bitavu, a visual template editor with a JSON-to-PDF API. This is one of the boundaries I care about: letting a coding agent build the integration while giving the team a clear place to maintain the document.

The first export is only one part of the job

A task called "add PDF export" leaves plenty open to interpretation.

Which data belongs in the report? What happens when it spans several pages? Who approves a layout change? Does saving a new design immediately affect production?

An agent can produce a working implementation without those questions being settled.

If the acceptance test only checks that a response starts with a PDF signature, a report with missing headings may pass.

Congratulations. You have successfully tested the existence of a file.

That check is useful. It just covers much less than the person reading the report will expect.

Give the agent a document contract

"Make it professional" leaves the agent to make choices about both presentation and integration.

A more useful starting point is a reviewed template and an explicit input shape.

Here is an illustrative request:

{
  "templateId": "client-report",
  "revision": 4,
  "data": {
    "report": {
      "title": "Delivery summary",
      "period": "2026-Q3"
    },
    "client": {
      "name": "Harbor Studio"
    },
    "sections": [
      {
        "heading": "This quarter",
        "body": "The implementation and review are complete."
      }
    ]
  }
}

Those IDs, revision numbers, and fields are examples. The real request must match a template saved in your workspace.

That gives the coding agent a bounded integration task: gather authorized application data, construct the expected payload, request the selected template revision, and handle the response.

At runtime, your application sends the JSON. The agent's work lives in the integration code.

The contract also makes future changes easier to discuss. A wider column is a layout change. A new required field changes what the application needs to supply.

Both deserve review, but they involve different work.

A brief you can give your coding agent

For a Bitavu integration, I would start with something like this:

Implement server-side report export using our existing application
authorization and the provided template ID, tested revision,
JSON field contract, and synthetic example data.

Use POST https://api.bitavu.com/v1/render.

Read the scoped API key from server configuration. Keep it out
of browser code, generated examples, and application logs.

Resolve report data through the authorized application user.
Keep the selected template ID and revision in server configuration.

Generate one idempotency key per logical export operation.
For retries of that operation, preserve the key, body, and revision.

Handle errors explicitly. A schema mismatch needs review;
do not invent a field mapping or switch to a different revision.

Return a successful PDF response as a download. Preserve useful
failure information without exposing credentials or report data.

Add checks for authorization, the expected document content,
multi-page data, schema mismatch, and retry behavior.

This is an ordinary HTTP integration. The valuable part of the brief is deciding what the agent may change and what should remain an explicit review decision.

If a field disappears, "keep trying until a PDF downloads" is a poor acceptance criterion.

A useful implementation tells you which contract stopped matching.

Give layout work a place to happen

In Bitavu Studio, document blocks bind to JSON fields. You maintain the layout visually and save template revisions; the application can request a tested revision through the API.

That creates a practical split:

The application team owns data selection, authorization, and the integration.

The people responsible for the document own its layout and review.

A colleague can work on the next template revision while production continues requesting its selected one. When the new layout is approved and tested, you adopt that revision deliberately.

If the change adds a required data field, the application team still needs to participate.

A visual editor gives the layout work a home. It does not erase the data contract.

A proposed fix still needs an owner

Suppose a generated report has a missing section.

A tempting fix is to make the section optional, substitute a blank value, or remove the failing check.

Any of those might make a test green. Whether it makes the report correct depends on why the section was required.

Give the agent that context before asking it to repair the output.

The same principle applies when AI helps with template changes. Bitavu's Studio assistant produces structured proposals that are validated and presented for review; applying a proposal is an explicit action.

Conceptual workflow illustration, not a Studio screenshot.

Review the effect on the document and its expected fields. A plausible proposal is a starting point for that review.

For API input that no longer matches the template, Bitavu reports detected schema drift as 422 SCHEMA_DRIFT. A reviewed, saved mapping can be referenced with mappingId. That is a deliberate adaptation to a particular template revision.

Test the handoff as well as the happy path

The most useful checks challenge the boundaries the agent was asked to preserve:

Situation	What to verify
A user requests another customer's report	Application authorization rejects the request
Realistic data spans multiple pages	Required content remains readable and pagination behaves as intended
An upstream field is renamed	The mismatch is visible rather than silently replaced with a blank
A render operation is retried	Its key, body, and selected revision stay consistent
A colleague edits the next template draft	The production request still selects its tested revision

Use synthetic fixtures with names, sections, and row lengths that vary. Inspect the generated pages as well as the response status.

For a fixed report that rarely changes, an agent-written renderer in your codebase may be enough. A separate template workflow becomes more useful when document changes keep arriving from several teams.

The next font change is coming either way.

When you ask an agent to build an export, what goes into your brief beyond "return a PDF"?

Disclosure: I'm building Bitavu. The three illustrations are AI-generated conceptual scenes using synthetic examples.

Your JSON is valid and your invoice is wrong

bitavu — Tue, 03 Nov 2026 19:21:22 +0000

Imagine a perfectly reasonable backend refactor.

client.name becomes customer.legalName. The new shape is clearer. The JSON parses. The application tests are green.

Then someone opens an invoice.

Beautiful margins. Correct logo. No customer.

The document has successfully generated an invoice addressed to absolutely nobody.

This is an illustrative failure in a loosely checked integration, but the underlying problem is useful to think about: valid JSON tells you surprisingly little about whether a document is correct.

I'm building Bitavu, a visual template editor with a JSON-to-PDF API. The boundary between incoming data and a saved document template is one of the places where a visible error can be much more useful than a successful download.

The customer did not disappear

Here is the data the template originally expected:

{
  "client": {
    "name": "Harbor Studio"
  }
}

And here is the new upstream shape:

{
  "customer": {
    "legalName": "Harbor Studio"
  }
}

Both are valid JSON. Both contain the same company name.

But a template bound to client.name does not automatically understand that customer.legalName is its replacement.

If the integration quietly converts a missing value into an empty string, the PDF may still render. The mistake has simply moved from an error response into a document someone will send.

The refactor is reasonable. The unchanged binding is the problem.

Three different checks are involved here:

Syntax: can the input be parsed as JSON?
Structure: does it contain the paths and types the template requires?
Meaning: are those values the right ones for this document?

Passing one does not prove the others.

A blank string is not always a fallback

Some fields really are optional. An absent delivery note might reasonably leave no visible text.

A missing billing recipient deserves a different decision.

If the document requires a customer name, make that requirement explicit before rendering. Even a small guard is better than quietly substituting a blank:

function requireClientName(data) {
  const name = data?.client?.name;

  if (typeof name !== "string" || name.trim() === "") {
    throw new TypeError("Expected a non-empty client.name");
  }

  return name;
}

This checks one field. A real document contract needs to cover its other required fields, types, arrays, and allowed values too.

Notice what happens with the refactored payload: the guard fails.

That is useful. You now have a specific integration change to review before an invoice leaves the system.

An empty string would have been quieter. The customer would have discovered the problem for you.

The more convincing bug passes the type check

Now suppose the input contains both of these:

{
  "billing": {
    "name": "Harbor Studio"
  },
  "shipping": {
    "name": "Harbor Warehouse"
  }
}

Both names are present. Both are strings. Both look like sensible things to put on a business document.

Only one belongs in this invoice's Bill to field.

This is why a mapping can be technically valid and still be wrong.

A structural validator can check that a string exists at a declared path. It cannot infer which business entity you intended to bill just because two field names look related.

When you review a mapping, ask a more useful question than "does the preview have text now?"

Ask: "Is this the person or company the document is supposed to name?"

The wrong name often looks more finished than a blank one. That does not make it a better result.

Treat a proposed mapping like a code change

For the first example, a deliberate mapping might be:

customer.legalName → client.name

That is a small transformation with a specific meaning: this upstream legal name supplies this template's client name.

Review it against the document's purpose. If an AI tool proposes the mapping, the same review still applies. A plausible field match is a proposal, not evidence that the two fields mean the same thing.

Before adopting it, use a few synthetic examples:

Input case	Expected result
A normal customer legal name	The intended name appears in Bill to
Billing and shipping names that differ	The billing recipient is used
A missing or blank required name	An explicit failure rather than a blank recipient
A number where the name should be	A type error rather than silent coercion

The second case is especially helpful. If every name in your fixture is "Test Company," the wrong mapping can look perfectly correct.

Give the warehouse a different name. Let your test data disagree with itself in the ways real data does.

Make the mismatch visible

In Bitavu, a detected schema mismatch is reported as 422 SCHEMA_DRIFT. After reviewing a transformation, you can save a mapping and reference its mappingId in render requests.

Saved mappings target a particular template revision. That gives the reviewed transformation a defined destination instead of treating it as a universal fix for every document.

Conceptual workflow illustration, not a Studio screenshot.

That mechanism helps make the mismatch explicit. It still needs a well-defined template contract and a person who understands what the fields mean.

The useful outcome is a document whose data and presentation have both been checked.

A green check beside "valid JSON" cannot do all of that work.

What is harder to catch in your documents: a missing value, or a completely believable wrong one?

Disclosure: I'm building Bitavu. All four illustrations are AI-generated conceptual scenes using synthetic examples.

Your PDF export is becoming a second frontend

bitavu — Tue, 03 Nov 2026 18:33:39 +0000

The ticket says "Add PDF export."

Four words. Very calm words.

You build an invoice. Three line items. One page. The logo is where logos traditionally live.

Then someone adds a longer company name, 87 line items, and a payment note.

The total lands on page three. The footer starts a solo career.

The file still downloads successfully. Apparently, everything is fine.

A successful render and a usable document are two different acceptance criteria.

I'm building Bitavu, a visual template editor with a JSON-to-PDF API. This is the design problem behind it: how do you let a document evolve without making every layout adjustment another application change?

The useful answer starts with how you test and release the template.

The first PDF is the easy one

A demo invoice is an extremely cooperative customer.

It has a short name. Its address fits. Its three descriptions are roughly the same length. It would never order enough things to inconvenience your page margins.

Real documents have less interest in your demo.

A request like "make the description column wider" can change row heights. Those heights affect page breaks. A page break can separate a total from the lines that explain it.

That is how a small layout change earns a surprisingly large review.

Treating the template as something you can test and release gives you a way to handle that review deliberately.

Give the layout its own home

There are two different jobs inside an invoice.

Your application knows what happened: who bought what, which amounts apply, and when payment is due.

The template decides how to present it: columns, spacing, branding, repeated headings, and where content continues onto another page.

A useful boundary looks like this:

Application data + tested template revision → PDF

That boundary can live entirely in your own codebase. You do not need a separate service to adopt it.

What matters is being able to change the layout while keeping its expected input clear.

In Bitavu Studio, that separation is expressed through visual document blocks, JSON bindings, and saved template revisions. A repeating table can take its rows from an items array; the backend supplies the data.

The visual editor gives layout work a place to happen. You still need to review the result.

Give your invoice some deeply inconvenient data

Before changing the design, save a small set of synthetic fixtures.

Start with a tidy invoice so you can spot obvious mistakes. Then make the data less polite.

Fixture	What to check
One item, then enough items to span several pages	Table continuation, repeated headings, and footer placement
The last row count that fits, then one more row	The exact transition onto the next page
A long company name and multi-line address	Wrapping and the space left above the table
One very long item description	Row splitting and whether its quantity and amount remain easy to associate
Missing optional notes or address lines	Intended fallbacks and unwanted blank space
Names with accents and symbols used by your customers	Font coverage, shaping, and alignment

The "one more row" case deserves special attention.

If 18 rows fit and 19 spill over, keep both fixtures. Those numbers belong to that particular template, font, and data; they are not a universal page capacity.

Also try the same row count with longer descriptions. Counting rows alone will not tell you how tall a table becomes.

The goal is to find the point where the layout changes behavior, then keep a test on either side of it.

Your least cooperative fake customer is doing valuable work here.

Make the backend request boring

Once the template has a clear input shape, the integration should be straightforward.

Here is a synthetic Bitavu invoice request. Save it as request.json:

{
  "templateId": "invoice",
  "revision": 3,
  "data": {
    "invoice": {
      "number": "INV-2027-014",
      "date": "2027-01-12",
      "due": "2027-02-11"
    },
    "client": {
      "name": "Bitavu Studio",
      "address": "74372 Washington Ave\nColumbus, 7206"
    },
    "items": [
      {"description": "Brand strategy workshop", "quantity": 1, "unitPrice": 650},
      {"description": "Design system", "quantity": 3, "unitPrice": 280},
      {"description": "Project support", "quantity": 2, "unitPrice": 95}
    ],
    "notes": "Thank you for working with us."
  }
}

invoice and revision 3 identify the example. Use a saved template ID and revision from your own workspace, with data that matches its bindings.

With your scoped API key in BITAVU_API_KEY, this Bash example creates a key for one render operation and sends the request:

# Create once for this operation. Reuse it for this operation's retries.
BITAVU_RENDER_KEY="$(node -e 'console.log(require("node:crypto").randomUUID())')"

curl --fail-with-body --retry 2 --retry-delay 2 \
  https://api.bitavu.com/v1/render \
  -H "Authorization: Bearer $BITAVU_API_KEY" \
  -H "Idempotency-Key: $BITAVU_RENDER_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json \
  --output invoice.pdf

The successful response is the PDF itself.

Keep the API key on your server. For a new operation, generate a new idempotency key. For a retry of the same operation, preserve the key, request body, and template revision.

If you retry later, do not rerun the key-generation line and accidentally turn the retry into a new operation.

A saved design should not surprise production

Suppose production requests revision 3.

You adjust the column widths and save a new revision. Production should keep using 3 while you review the change.

A practical release sequence is:

Render the saved fixtures against the candidate revision.
Check the resulting pages, especially the page-boundary cases.
Approve the layout and confirm that the application's data still matches.
Update the revision requested by production.

A revision pin controls which template you request. It is not a promise that every byte of every PDF will be identical: renderer changes, fonts, and referenced assets also matter.

For the same reason, a PDF binary diff is a poor substitute for checking the document. Metadata can change without changing the page; a misplaced total can matter enormously even though the file opens.

If a field changes from client.name to customer.legalName, treat that as an integration change too. Moving the layout into an editor does not make the data contract disappear.

When a visual editor earns its place

For one fixed document that rarely changes, a small rendering function in your application may be all you need.

The balance shifts when layouts keep changing, several templates share branding, or someone needs to adjust the document without editing application code.

That is the workflow I'm building Bitavu for: a visual place to maintain the template, with a versioned API for the application that uses it.

You still choose the data contract. You still test the awkward cases. You get a clearer place to make and review the layout changes.

The paper monster gets a new job.

What is the most uncooperative thing you have ever had to fit on an invoice?