DEV Community: Mariano Barcia

HappyGF: I Built an AI Assistant to Make Sure Contractors Get Paid on Friday

Mariano Barcia — Mon, 19 Oct 2026 05:09:25 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle.

What I Built

Every Friday, the accountant processes payments to the contractors and suppliers who keep my girlfriend's business running. For that to happen, invoices need to be received, reviewed, approved, correctly named, and forwarded to the accountant before the deadline.

It sounds straightforward, until you consider how many invoices arrive by email, often from different contractors, in different formats, with different naming conventions—or none at all.

The accountant requires PDF filenames containing the vendor, property, and invoice amount, following a specific convention. My girlfriend was spending far too much time opening attachments, checking details, renaming files, and forwarding them. Worse, mistakes or delays could mean someone didn't get paid that Friday.

That's how HappyGF, an AI-powered accounts payable assistant, came about.

The application helps her process incoming vendor invoices, extract the relevant information, prepare correctly named PDFs, and get approved invoices ready for the accountant.

It also remembers what has already been processed. Recently, a contractor accidentally submitted the same invoice twice. HappyGF recognized the duplicate instead of treating it as another invoice to process. A small detail, perhaps, but an important one when dealing with payments.

This isn't an experiment looking for a use case. She's already using the application for real work, and I'm now releasing an open-source edition for other businesses dealing with similar accounts payable workflows.

Demo

Video: https://youtu.be/Ttzg6bqgyA8

The demonstration uses fictional vendors, properties, and invoices to show the workflow from incoming email to an accountant-ready PDF.

Code

GitHub: https://github.com/MokapotLabs/invoice-assistant

The open-source edition includes the application, configuration, tests, and instructions for running it.

How I Built It

HappyGF is written in Java using The Pipeline Framework (TPF), an open-source framework I've been developing over the past few years.

One thing I learned along the way is that not every AI task needs the same model. Reading an unfamiliar invoice, recognizing a company logo, and deciding which property an invoice belongs to are different problems.

The open-source edition uses three models through Ollama:

Qwen 3.5 4B for invoice text analysis.
Qwen3-VL 4B for visual recognition, including company logos.
Tev1 for structured supplier and property decisions.

Tev1 is particularly interesting. It's a small, open-weight decision model that uses the same Jev-style API as the hosted decision service I've been using. Rather than asking a generative model to produce another paragraph of text, the application can ask a specific question, supply possible answers, and receive a structured decision.

Once the invoice has been interpreted, ordinary application code applies the filename convention, tracks processing state, detects duplicates, and manages the approval workflow. The AI assists with interpretation; it doesn't get to authorize payments or bypass business rules.

Microsoft Graph provides the Outlook integration, while TPF handles the typed pipelines, persistence, external operations, and execution concerns.

Local AI sounded perfect. Then I tried running it on an 8 GB MacBook.

My original intention was to keep inference local, using Ollama. It works, and I've used it extensively for development and automated testing.

Unfortunately, the application isn't something my girlfriend uses continuously. She opens it when there are invoices to process, and Ollama may need to load the models into memory. Some invoices also require visual recognition, which means switching models.

On her 8 GB MacBook, that can turn into a one- or two-minute wait. Not exactly the experience you want when you're trying to get through a pile of invoices before Friday.

Running Ollama on another machine would help, but keeping another computer running just to process a few invoices each week feels rather wasteful.

So I tried hosted inference through OpenRouter.

The current hosted setup uses Gemini 3.1 Flash Lite and Jev 1.13. It's fast, requires no local model installation, and the API key has accumulated less than four US cents in usage so far.

Introducing Jev also made a noticeable difference to cost. By moving suitable decisions away from the generative model, I've seen roughly a 50% reduction in inference spending.

These are observations from a lightly used application, not a controlled benchmark, but they surprised me. At this volume, inference costs are practically negligible compared with the time saved.

The open-source edition retains Ollama support, so users can choose local inference instead.

Why Does Open Innovation Matter?

The experience with HappyGF has changed how I think about local AI.

Invoices contain commercially sensitive information, including supplier identities, properties, amounts, and business correspondence. Running open-weight models locally means that information doesn't have to leave the business's own hardware for AI inference.

But local execution comes with costs of its own: memory, processing power, model loading, and maintenance. On modest hardware, those costs can make a perfectly functional application unpleasant to use.

Hosted inference offers a different balance. OpenRouter provides controls over prompt logging, provider data collection, and zero-data-retention routing. Those protections are useful, but remote inference still requires sending information to an external provider, whose data-handling policies matter.

Open-weight AI gives us a choice; it doesn't mean local inference is always the best choice.

For HappyGF, the practical benefit of open innovation is the ability to experiment with smaller, specialized models, run inference locally when confidentiality requires it, and choose hosted alternatives when convenience matters more.

Tev1 is a good example. A small decision model can handle certain questions without invoking a larger generative model. And because both the application and TPF are open source, the surrounding workflows and business rules remain inspectable and adaptable.

The goal isn't to eliminate every external dependency. It's to avoid making any particular inference provider or model an architectural requirement.

My First User

My girlfriend has been using HappyGF for her actual accounts payable work.

She's responsible for ensuring that invoices reach the accountant in time for the weekly payment run, and the application was built around the problems she encountered doing that.

One recent incident illustrates its value particularly well: a contractor submitted an invoice twice. HappyGF identified the duplicate, avoiding another round of manual checking and reducing the risk of processing the same invoice again.

Her experience has driven the application's development, including decisions about which integrations are worth keeping and whether local inference is practical on the hardware she already owns.

She hasn't paid me for the application, but she uses it for real work. I'm interested in discovering whether other managers and accounts payable teams face similar problems and would find an open-source alternative useful.

Touch grass, and touch glass on a padel court

Mariano Barcia — Sun, 11 Oct 2026 11:52:24 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Arranging a padel match can be surprisingly tedious. You need four players of roughly similar ability, available at the same time, preferably with compatible expectations. In practice, this means checking club apps, messaging WhatsApp groups, negotiating times, and chasing people for confirmation.

I wondered whether personal AI agents could handle some of that coordination for us.

PadelPot is an experiment where four AI agents negotiate a doubles match on behalf of their owners. Each agent knows its player's preferences, can discuss possible arrangements with other agents, and asks its owner when a compromise or commitment requires approval.

The agents don't exchange complete player profiles. They negotiate using limited information, with privacy and commitment rules enforced by the application rather than left to the language model.

The idea behind Touch Grass is straightforward: less time arranging matches, more time playing them.

Demo

The demo follows four fictional players—Alba, Nico, Luz, and Teo—using a WhatsApp-style chat interface. Their agents negotiate a Thursday evening match, resolve a disagreement about the starting time, and obtain approval from all four players.

The conversations use actual Gemma inference rather than scripted responses.

Code

https://github.com/The-Pipeline-Framework/padelpot

The application is open source and includes setup instructions, synthetic player profiles, automated tests, and reproducible demonstration scenarios.

How I Built It

PadelPot is a Java application built using The Pipeline Framework (TPF), an open-source framework I've been developing for distributed applications.

It uses Google's open-weight Gemma models for interviewing players and negotiating between agents. I tested the application using Gemma through Ollama, running locally. It also supports inference through OpenRouter.

TPF provides the typed pipelines, agentic execution, persistence, and asynchronous human interactions. The application handles the matchmaking rules, privacy policies, and final approvals.

One interesting test sends 30 concurrent approval attempts to the same match. Despite the competing requests, the application never confirms more than four players.

The first working implementation took a little over an hour using an AI-assisted development workflow, although it builds on TPF infrastructure developed over several years.

This is a working demonstration with synthetic users, not a production matchmaking service. Real WhatsApp integration, court bookings, and independent hosting of personal agents remain outside its scope.

Why Does Open Innovation Matter?

The interesting part of PadelPot isn't simply generating text with an LLM. It's allowing several independently acting agents to negotiate while keeping their behavior constrained by ordinary, testable application rules.

Open-weight models such as Gemma make it possible to experiment with that behavior locally, inspect the results, change inference providers, and run integration tests without depending exclusively on a proprietary model API.

TPF is also open source, so the execution model and application architecture can be inspected, tested, and extended.

For an experiment involving personal information and autonomous agents, that openness matters.

Prize Categories

Best Use of Gemma

cross-repo testing anyone?

Mariano Barcia — Tue, 29 Sep 2026 16:37:17 +0000

Anyone on my network doing automated testing across multiple repositories / microservices? Curious to know how you are doing, I might have a well-defined product I'd like to build and would love some feedback.

On Jev and Athletics

Mariano Barcia — Fri, 25 Sep 2026 12:42:47 +0000

I think using AI every day has given us a slightly misleading idea of how easy automation is becoming.

Models have improved incredibly quickly. Give an AI a browser, some skills and a bit of context and it can do impressive things.

So it’s easy to think: surely automating the whole process is next.

I’m not so sure.

We’ve been running 100 metres with 30” hurdles — and still hitting a few — and now we’re talking about running 400 metres hurdles at the Olympics.

A skill that works while you’re watching is very different from something that has to work hundreds of times on its own.

Small problems multiply. A slow AI call repeated ten times becomes a slow process. Something that’s reliable 98% of the time doesn’t look nearly as good after twenty steps. Websites change, logins expire, bot protection gets tougher. And giving an AI access to everything it might need brings its own obvious problems.

This is one reason I’ve decided to integrate Jev into The Pipeline Framework.

Jev doesn’t try to solve all of that. It does something much narrower: make small decisions over supplied data very quickly and very cheaply.

And that compounds beautifully.

Data leads to a small decision, which produces more data, which informs another decision, and eventually the software does something.

That’s much more interesting to me than asking one enormous model to figure out the whole process.

Big types

Here’s the lovely coincidence I only noticed after integrating Jev.

The company behind it is called TypeSafe.

And strong typing is also one of the ideas at the heart of The Pipeline Framework (as is the case with many programming languages).

That’s not just a naming coincidence: Jev doesn’t return some prose and hope the application interprets it correctly. You give it a defined set of possible decisions and get a structured result back.

TPF takes the same idea further through the rest of the application: typed data goes into steps, typed data comes out, and those types connect AI decisions, ordinary code, human input and real-world actions.

Jev makes the decision faster and cheaper.

TPF makes the process around the decision something you can actually build software on.

It took me 18 hours to add Jev

Mariano Barcia — Wed, 23 Sep 2026 17:29:21 +0000

It took me 18 months to build The Pipeline Framework.

18 days to turn it into an AI operating system.

18 hours to add an entirely new kind of AI.

TypeSafe released Jev only days ago: a System One model that doesn’t generate language. It makes fast, bounded, probabilistic decisions.

TPF had been built around functional pipelines, "Functional Core, Imperative Shell", reactiveness, scalability, then generative LLMs, RAG, tools, agent loops, MCP, human interaction, durable effects...

So how much architecture would a fundamentally different model require? Turns out: almost none. So Jev became another Query provider.

invoice-judgment-model:
  provider: decision.query.jev
  version: 1
  config:
    model: typesafe/jev-1.13

I added a provider-neutral decision protocol:

DecisionRequest → DecisionResult

with bounded Choice, Noul and Score questions, then plugged Jev underneath it.

A real Java application was using it the same day — despite Jev not yet having an official Java SDK.

And I think that is the milestone I’m happiest about: not that TPF supports the latest AI model, but that it didn’t particularly care that it was new.

An LLM is a Query. RAG retrieval is a Query. A database lookup is, you guessed it, also a Query. So now a System One probabilistic decision is a Query, as it should.

Different computational models. Different latency profiles. Different semantics at the provider level. Same application architecture.

The first 18 months were spent finding the abstractions.

The next 18 days exploited them.

The next 18 hours barely disturbed them.

That’s the compounding return of solid architecture.

LLMs Generate. Jev Decides. Software Should Know the Difference

Mariano Barcia — Tue, 22 Sep 2026 16:37:18 +0000

Bringing TypeSafe's System One model into a real Java application with The Pipeline Framework

For the last few years, we have been solving an extraordinary range of software problems with essentially the same primitive:

send some context to a large language model and ask it to generate the answer.

That has worked relatively well, but it has also encouraged us to turn problems that are not fundamentally generative into generation problems.

Classification becomes generation.

Routing becomes generation.

Selecting one item from a known catalogue becomes generation.

Determining whether a condition holds becomes, you guessed it: generation.

And then, because a generative model is free to generate almost anything, we spend an increasing amount of effort constraining it:

Return exactly one of these values.

Do not invent identifiers.

Return exactly this JSON structure.

Do not include an explanation.

Do not wrap the result in another object.

Never return anything outside the supplied catalogue.

Structured output has made this considerably better. But there is still something slightly peculiar about the underlying architecture.

We are using a machine designed to generate an open-ended sequence of tokens, and then asking it very politely not to be open-ended.

TypeSafe's Jev presents a fascinating alternative.

And when we integrated Jev into The Pipeline Framework and then used it in a real invoice-processing application, something became very clear:

some of the work we were giving to an LLM was never an LLM problem in the first place.

System One: AI as a decision function

TypeSafe describes Jev as the first of its System One Models: models designed not primarily to generate language, but to make fast, structured decisions that software can consume directly.

Instead of an open-ended generation operation, the abstraction is closer to a bounded decision function.

flowchart LR
    S[State] --> G[Generative model]
    G --> T[Open-ended tokens]

versus:

flowchart LR
    S[State] --> D[Bounded questions]
    D --> J[System One model]
    J --> R[Probabilistic decisions]

The distinction is profound.

TypeSafe currently exposes three particularly useful decision shapes: Choice, Noul, and Score.

A Choice selects from a finite set of alternatives and returns the corresponding probability information.

A Noul evaluates a proposition probabilistically.

A Score evaluates something against an ordered scale.

Several independent questions can be evaluated against the same state in one request.

The output is not primarily prose intended for a human reader. It is information intended for software.

That changes what the model is being asked to do.

Consider the difference.

A generative approach says:

Read this invoice and tell me which property it belongs to. Return exactly one ID from this list and do not invent another one.

A bounded decision instead defines:

Which property?

Choice:
    PROPERTY_A
    PROPERTY_B
    PROPERTY_C

In the first case, selecting a valid identifier is a prompt requirement.

In the second, it is part of the decision domain.

That is a much stronger contract.

We happened to have exactly the right application

At Mokapot Labs we maintain a small application called Invoice Assistant.

It is built with The Pipeline Framework (TPF), an open-source framework for constructing typed processing applications.

The application receives an invoice and a property catalogue, extracts invoice information, determines which property the invoice belongs to, optionally performs visual analysis when the supplier cannot be established from text, presents the result for human confirmation, and then performs the required external effects.

Its pipeline includes ordinary computation, AI inference, branching, a human Await boundary and replay-safe Commands.

Before Jev, its text-analysis stage looked roughly like this:

flowchart TD
    A[Invoice] --> B[Extract document text]
    B --> C[Gemma 12B]
    C --> C1[Extract supplier/invoice nr/amount]
    C --> C4[Classify supplier evidence]
    C --> C5[Select property]
    C --> C6[Explain recommendation/w note]
    C1 --> D[Route supplier evidence]
    C4 --> D
    C5 --> D
    C6 --> D
    D -->|Sufficient| E[Review]
    D -->|Insufficient| F[Vision model]

This worked.

It was not disastrously slow. It was not unreliable enough to force a redesign.

But the LLM call was doing several fundamentally different jobs.

And our prompt showed it.

The old prompt contained the clue

Part of the original prompt said:

Classify supplier evidence with exactly one qualitative
supplierEvidenceStatus:

EXPLICIT_TEXT
STRONG_TEXTUAL_IDENTITY
INSUFFICIENT

Another part said:

Select exactly one property ID present in the supplied
catalogue.

Do not invent, rewrite or normalize property IDs.

Read those requirements again in the context of a System One model.

They describe Choices.

We had an LLM generating a result and a prompt instructing it to behave as though the output space were closed.

But the output space really was closed.

For supplier evidence, there were three possible answers.

For the property recommendation, the possible answers were precisely the properties already supplied to the application.

The problem was not:

Generate a property identifier.

It was:

Choose one of these properties.

That difference sounds small.

Architecturally, it is enormous.

But not everything was a Choice

This is where the distinction becomes useful rather than ideological.

The application also needs to determine:

supplier      = "Some arbitrary company name"
invoiceNumber = "INV-2026-18473"
totalAmount   = 68.52

Those are open-world values.

The supplier can be a string we have never encountered before.

The invoice number is arbitrary.

The amount is arbitrary.

These are extraction problems, and our existing generative LLM remains well suited to them.

So we did not replace the LLM with Jev.

We split the problem according to its semantics.

The result became:

flowchart TD
    A[Invoice] --> B[Extract document text]
    B --> C["Generative LLM<br/>Gemma"]
    C --> C1[Supplier]
    C --> C2[Invoice number]
    C --> C3[Total amount]

    C1 --> D[Prepare DecisionRequest]
    C2 --> D
    C3 --> D

    D --> J["Jev<br/>System One"]
    J --> J1["Supplier evidence<br/>Choice"]
    J --> J2["Property<br/>Choice"]

    J1 --> P[Probabilistic judgments]
    J2 --> P

    P --> R[Deterministic application policy]
    R -->|Sufficient evidence| H[Review]
    R -->|Insufficient evidence| V["Existing vision model<br/>VLM"]

The generative model generates.

The decision model decides.

The application governs what happens next.

That separation turned out to be more important than simply changing model providers.

The LLM prompt got dramatically smaller

The revised generative step now has a much narrower job:

Extract only the supplier, invoice number and total amount
from the invoice evidence.

And, perhaps more revealingly:

Do not classify supplier evidence,
select a property,
explain a choice,
generate a note...

The LLM is no longer responsible for everything that happens to involve semantic understanding.

It is responsible for the part of the problem that genuinely requires open-ended extraction.

That is an important architectural lesson.

"Uses AI" is not a sufficient reason for two operations to belong to the same model call.

Their semantic shapes matter.

The System One decision is ordinary Java

There was another complication.

TypeSafe currently publishes official Python and JavaScript/TypeScript SDKs, but not an official Java SDK.

Invoice Assistant is a Java application.

We could have waited.

We could have introduced Python into the application.

We could have written a thin application-specific HTTP client.

Instead, this became an opportunity to establish something more reusable in The Pipeline Framework:

a provider-neutral Java protocol for bounded AI decisions.

The application constructs an ordinary DecisionRequest.

For supplier evidence, it declares:

new DecisionQuestion(
    "supplierEvidence",
    DecisionQuestionType.CHOICE,
    "Judge only the strength of textual evidence identifying the invoice supplier.",
    List.of(
        new DecisionCriterion(
            "EXPLICIT_TEXT",
            "The issuer or supplier is directly labelled or named."),
        new DecisionCriterion(
            "STRONG_TEXTUAL_IDENTITY",
            "Several consistent textual identity cues identify the issuer."),
        new DecisionCriterion(
            "INSUFFICIENT",
            "Text is absent, generic, conflicting, or ambiguous.")))

The property decision is constructed dynamically from the application's actual property catalogue:

result.properties().forEach(property ->
    properties.add(
        new DecisionCriterion(
            property.id(),
            property.displayName()
                + "; "
                + property.canonicalAddress()
                + "; aliases: "
                + String.join(", ", property.aliases()))));

Then:

new DecisionQuestion(
    "property",
    DecisionQuestionType.CHOICE,
    "Select the supplied property best supported by the invoice evidence.",
    properties)

This is one of my favourite consequences of the change.

Previously we told the LLM:

Do not invent property IDs.

Now the set of possible property IDs is the decision.

The safety property moved from prose into structure.

One state, multiple judgments

The application constructs a state containing the information Jev actually needs:

extractedFacts
invoiceText
originalFilename
properties

and submits both questions together.

flowchart TD
    S["Decision state<br/>extractedFacts<br/>invoiceText<br/>originalFilename<br/>properties"]
    S --> R[DecisionRequest]
    R --> Q1["supplierEvidence<br/>Choice"]
    R --> Q2["property<br/>Choice"]
    Q1 --> J[Jev]
    Q2 --> J
    J --> A1["Supplier evidence judgment<br/>choice + probabilities"]
    J --> A2["Property judgment<br/>choice + probabilities"]

That maps naturally onto the System One model.

The application is not conducting an agent conversation with the model.

It is not asking one question, parsing the answer, constructing another prompt and asking another question.

It describes the state and the bounded judgments it requires.

The model evaluates them and returns structured results.

That is a much more application-shaped interaction.

The model judges. Software governs.

This may be the most important architectural property of the whole integration.

Jev does not decide whether the pipeline should execute visual analysis.

It does not decide whether the application should ask a human.

It does not execute another capability.

It doesn't become the workflow engine.

It returns judgments.

The application then applies policy.

flowchart TD
    J[Jev] --> P["Probabilistic judgments"]
    P --> A["Deterministic application policy"]
    A -->|Text evidence accepted| R[Review]
    A -->|More evidence required| V[Vision analysis]

This boundary matters.

A probabilistic model is excellent at answering questions such as:

Which supplied property is most strongly supported by this evidence?

It should not automatically acquire authority over:

What should the business process do next?

Those are different concerns.

TPF makes that distinction very natural.

This is where The Pipeline Framework gets interesting

At first glance, integrating a new AI model might sound like a framework feature:

kind: jev

We deliberately did not do that.

Jev is not a new kind of pipeline operation.

From TPF's perspective, Jev observes something the pipeline does not currently know.

That makes it a Query.

TPF's semantic rule is simple:

known execution-local data   → carry it
fresh external observation   → Query
external side effect         → Command
deferred external completion → Await

Whether the external observation came from PostgreSQL, an HTTP API, an LLM or a System One decision model does not fundamentally change that semantic boundary.

So the pipeline contains:

- name: Judge Invoice
  kind: query
  cardinality: ONE_TO_ONE
  input: InvoiceJudgmentRequest
  output: InvoiceJudgmentResult
  using: invoice-judgment-model
  operation: decide
  operationVersion: 1

and the provider binding is:

invoice-judgment-model:
  provider: decision.query.jev
  version: 1
  config:
    model: typesafe/jev-1.13
    connection: openrouter-primary

That is all the pipeline needs to know.

There is no Jev step kind.

There is no System One workflow engine.

There is no Jev-specific branch operator.

There is simply another typed external observation.

Provider-neutral protocol, provider-specific implementation

This distinction is crucial for avoiding framework lock-in.

The application does not model its domain using Jev's Python SDK classes.

Its canonical pipeline types refer to:

<tpf.decision.DecisionRequest>
<tpf.decision.DecisionResult>

The application code constructs:

DecisionRequest
DecisionQuestion
DecisionCriterion
DecisionQuestionType

The provider happens to be decision.query.jev today.

The conceptual layering is therefore:

flowchart TD
    A[Application domain]
    A --> P["TPF bounded-decision protocol<br/>DecisionRequest / DecisionResult"]
    P --> Q["TPF Query<br/>decide / v1"]
    Q --> X[Provider adapter]
    X --> J[Jev]
    X -. future .-> O[Another bounded-decision engine]

This is substantially different from writing an unofficial Java clone of TypeSafe's SDK.

TPF is defining the capability the application needs.

Jev is implementing it.

That leaves the application architecture independent of one vendor's client library.

Java gets a native System One path in the process

This has an interesting practical consequence.

TypeSafe's official SDKs currently target Python and JavaScript/TypeScript.

TPF applications can nevertheless use Jev from Java through ordinary typed application code.

There is no requirement for a Python sidecar.

flowchart TD
    J[Java application] --> DR[DecisionRequest]
    DR --> Q[TPF Query]
    Q --> A[decision.query.jev]
    A --> V[Jev]
    V --> RS[DecisionResult]
    RS --> J

Nor does application code need to manually construct vendor HTTP payloads.

And because the Java-facing contract is provider-neutral, this integration is useful beyond Jev itself.

It establishes bounded probabilistic decisions as an application capability in the Java ecosystem rather than merely exposing one vendor endpoint.

The output contract became better too

The old property recommendation contained:

propertyId
explanation

The new result contains:

propertyId
confidence
probabilities[]

Supplier evidence similarly carries:

status
confidence
probabilities[]

This represents a significant change in what the application expects from AI.

flowchart LR
    subgraph Before
        A1[AI] --> A2[Answer]
        A1 --> A3[Prose explanation]
    end

    subgraph After
        B1[AI] --> B2[Judgment]
        B1 --> B3[Confidence]
        B1 --> B4[Probability distribution]
    end

We had originally added explanations partly as a crutch while introducing the first real LLM Query into the application.

But prose explanation and model uncertainty are not the same thing.

A convincing explanation does not necessarily mean a model is confident.

A terse answer does not necessarily mean it is uncertain.

For application decisions, explicit probabilistic information is often much more useful.

The application can inspect it.

Policy can act on it.

Telemetry can record it.

Humans can see uncertainty where useful.

And future policy changes do not require rewriting a prompt merely to change what confidence means operationally.

Dead generative work disappeared

The refactoring also exposed functionality that no longer justified its existence.

The old model generated a short mnemonic note.

In practice, it was not used.

So it disappeared.

The recommendation explanation had largely existed to make early LLM behaviour inspectable.

It disappeared too.

This is another benefit of decomposing model responsibilities.

Large prompts have a tendency to accumulate requirements because adding another sentence feels cheap:

While you're there, also generate...

But inference responsibilities then become coupled together.

Once the application explicitly separates extraction, decision, policy and presentation, each output has to justify why it exists.

That is healthy architecture, AI or otherwise.

TPF's Functional Core / Imperative Shell model survives AI

One of the recurring problems in agentic systems is that the model gradually absorbs application architecture.

The model decides what to call.

The model decides whether to retry.

The model decides what state matters.

The model decides when the workflow is finished.

Eventually the "application" becomes a prompt wrapped around a tool registry.

TPF deliberately takes another direction.

The pipeline owns composition.

Canonical types own application contracts.

Queries own fresh observations.

Commands own external effects and, optionally, deferred completion.

Ordinary application functions own deterministic business policy.

AI fits inside those boundaries rather than replacing them.

Invoice Assistant demonstrates that particularly well.

The model can judge:

supplierEvidence =
    STRONG_TEXTUAL_IDENTITY

confidence =
    0.x

but ordinary application code determines what that means for the workflow.

Likewise, Jev may select a property, but it does not archive the invoice.

Archiving is an external effect and therefore remains a TPF Command.

Human property confirmation does not become an agent loop waiting in memory; that, remains an Await boundary.

flowchart TD
    P[Typed TPF pipeline]

    P --> Q[Query]
    P --> C[Command (and await)]

    Q --> O[Fresh observation]
    C --> E[External effect]

    O --> L[Generative LLM]
    O --> J[System One / Jev]
    O --> X[Database / API / other provider]

AI becomes part of software architecture rather than a replacement for it

One does not simply @Inject in TPF

Mariano Barcia — Thu, 03 Sep 2026 22:50:05 +0000

I remember IntelliJ IDEA constantly nudging me away from field injection and toward constructor parameters. Funny how relevant that feels now. The principle was sound: make dependencies explicit.
A pipeline should say what it needs, where it comes from, and how it flows—without invisible framework magic: TPF applies that instinct to the whole application.

https://pipelineframework.org

Where the business actually lives

Mariano Barcia — Thu, 09 Jul 2026 18:04:01 +0000

Read the previous episode here:

Mariano Barcia

May 21

Data fails first

#tpf #java #quarkus #datascience

3 min read

Software has a strange way of rewarding patience.

When Marta first introduced TPF into the project, some of her colleagues quietly wondered if the pipeline would become just another obstacle everyone would have to avoid. A few months later, those worries faded. The framework became background noise, the business continued to develop, and people only discussed the architecture when they really needed to.

Marta thought that was probably a good sign.

In the meantime, the application had evolved. A second developer joined the team, another carrier integrated, customer support got a small dashboard to check failed orders, and finance requested a daily reconciliation process. None of these changes altered the application's core function. They simply made it more useful.

Looking back, Marta realized this was exactly the evolution she had hoped for. The pipeline lengthened in some areas, new operators appeared, the generated contracts changed with the business, yet the application felt reassuringly familiar. Reading the pipeline from top to bottom still felt a lot like reading a business process. The architecture remained mostly hidden.

At least, that’s what she thought.

Daniel spent most of the previous week adding support for another shipping provider. The implementation went smoothly, but during the code review, he hesitated over a change that seemed harmless at first.

“I changed the pipeline here,” he said, pointing at the screen, “but I’m not sure the business has changed.”

Marta leaned in.

The modification was exactly what she expected. One integration replaced another. The tests passed. The contracts still matched. It was technically sound.

“What’s bothering you?”

Daniel took a moment before he replied.

“I’m not sure yet.”

He closed the pull request without merging it.

Later that afternoon, Marta found herself at the coffee machine with Elena. Elena had a knack for listening just enough to ask the right question.

“You look like you’re debugging something that isn’t broken,” Elena said.

Marta smiled. “Daniel changed a pipeline step. Everything works. But he thinks the business didn’t change.”

“And you think?”

“I think he’s right. I just don’t know why.”

Elena leaned against the counter. “Walk me through it.”

Marta hesitated for a moment but then began.

“Orders come in. We validate them. We reserve inventory. We authorize payment. Then we hand things off to the warehouse.”

“Sounds like a business,” Elena said.

“It does. But in between, there are steps that don’t feel like that. We wait for a payment provider. We publish messages. We react to callbacks.”

Elena nodded slowly. “So?”

“If I read the pipeline as ‘this is how our business works’, some parts feel... different.”

Elena picked up her cup. “Different how?”

Marta thought for a moment. “If we stopped validating orders, the business wouldn’t exist. The same goes for inventory or payment decisions.”

“What about the other parts?”

“If we changed how orders arrive, or how the warehouse gets notified, the business wouldn’t describe itself any differently.”

Elena smiled. “So some steps are the business. Others are just how the business talks to the world.”

Marta blinked. “Yes. Exactly.”

They stood there for a moment.

“So what will you do about it?” Elena asked.

Marta shrugged lightly. “Nothing dramatic. Just… stop pretending they’re the same thing.”

Elena laughed. “That’s usually a good start.”

Back at her desk, Marta reopened the pipeline and read it again, this time thinking of Elena’s words; some steps showed decisions the business cared about, and others showed conversations the application needed to have.

They were all necessary, but they were not the same.

She leaned back, thinking how right had Daniel been to hesitate and point out the new code hadn’t changed the business, and revealed where the business actually was.

Data fails first

Mariano Barcia — Thu, 21 May 2026 14:56:57 +0000

The strange thing was that the first real scaling problems had nothing to do with scale. Or at least, scale as in "infrastructure scale".

The application was still relatively small. Traffic was growing, yes, but nothing dramatic. CPUs were healthy, latency was acceptable, deployments remained pleasantly uneventful. From the outside, the system still looked exactly like what it technically was: a single Quarkus application running as a monolith, with pipeline steps invoking one another directly inside the same process.

And yet developers had started speaking about it differently.

Not formally. Nobody walked into a meeting and announced that “the architecture had changed.” It emerged indirectly, through the kind of comments engineers make when systems begin slipping away from them:

“Be careful changing that field.”
“I think another step depends on this.”
“We should probably keep the old format for compatibility.”
“I’m not entirely sure who consumes this anymore.”

The incidents themselves were subtle enough to avoid triggering panic. Customer support found two apparently identical shipments taking different routing paths. Finance noticed that premium customers occasionally missed SLA prioritization. A new carrier integration introduced a field named region, while another team added shipping_region, and for several months both quietly coexisted because somewhere in the middle of the pipeline a mapper handled the ambiguity without anybody realizing it.

Nothing crashed.

That was precisely the problem.

The failures were no longer technical failures. They were semantic failures. The system continued running while different parts of the application slowly stopped agreeing on what the data actually meant.

Marta recognized the smell immediately because she had seen it before in event-driven and serverless systems: payloads beginning life as wonderfully flexible JSON blobs and gradually hardening into undocumented distributed contracts. Except this time, it was happening entirely inside a monolith.

That realization bothered her more than any infrastructure issue they had faced so far because it exposed something most engineers rarely think about when they talk about distributed systems.

When people hear “distributed systems,” they usually imagine the visible mechanics:

remote calls
retries
eventual consistency
latency
concurrency
partitions

But those are often second-order effects. The deeper problem appears much earlier, when independently evolving parts of a system begin sharing meaning imperfectly.

Two teams interpreting the same field differently. A payload surviving longer than the assumptions under which it was created. Producers and consumers changing independently without realizing the semantic contract between them has drifted.

That is already a distributed systems problem, even if everything still runs inside one JVM.

And that was the moment Marta realized something important:

Distribution is not a deployment problem. It starts as a data problem.

The architecture diagrams had not changed yet, but the organizational reality already had. Different teams owned different stages of the pipeline. External integrations introduced their own semantics. Some transformations were deterministic and easy to reason about; others depended on databases, carrier APIs, fraud services, and infrastructure outside the team’s control. The application might still have been physically centralized, but conceptually it had already become a collection of independently evolving boundaries.

That was where TPF started becoming much more than a convenient orchestration framework.

The team was not using it as a generic workflow interpreter where loosely defined tasks execute dynamically at runtime. What TPF increasingly provided was something much closer to a typed application pipeline compiler: a system capable of understanding the boundaries between stages well enough to generate contracts, validate transformations, wire transports, expose endpoints, and fail builds when parts of the pipeline drifted out of alignment.

The distinction mattered enormously.

The pipeline steps themselves remained ordinary application code. Developers wrote Quarkus services, plain Java methods, some reactive Mutiny handlers where concurrency justified the complexity, some blocking implementations where simplicity mattered more than theoretical throughput. Nobody had to abandon the normal ergonomics of application development to “enter the workflow engine.”

But the boundaries between those steps became explicit.

Instead of passing anonymous maps through the system and hoping conventions would survive organizational growth, stages now declared typed inputs and outputs, mapper rules, cardinality expectations, operator contracts, and transport compatibility in ways the compiler could actually verify.

The effect on development was immediate and surprisingly human. Refactoring became less frightening. Teams stopped relying on tribal knowledge to understand dependencies. A mapper mismatch became a compilation error instead of a production incident discovered three weeks later through telemetry dashboards and apologetic Slack messages.

Peace of mind was alas, restored, once all the data contracts between steps were formalised, and the architecture stopped evolving accidentally.

The Lift and Shift

Mariano Barcia — Thu, 07 May 2026 18:12:31 +0000

This is the continuation of "The script that refused to stay small".

The conversation had already been happening for months: three data centers, rising costs, aging hardware, and a growing sense that the whole setup was one incident away from becoming a liability.

The decision came quickly after the "kalima" event: everything had to move.

What followed was not elegant, as the platform team scrambled to pull off a lift & shift to the cloud:

hypervisor VMs mapped 1:1 into cloud instances
network rules replicated (and occasionally guessed)
storage reattached, sometimes awkwardly
timelines optimistic, then revised, then ignored

Most applications... just came along for the ride whilst Marta watched all of this unfold.

Her service was, technically, just another VM in the inventory. It could have been copied over, like everything else, but the lift and shift was rushed and was accumulating tech debt almost by definition. So she made a different call.

Instead of following the 1:1 VM migration path, she opted into an early container platform the company had been experimenting with—something not yet standard, slightly under-documented, but good enough.

Not because she was trying to be innovative, but because her system made it easy.

Containerizing the application turned out to be almost trivial.

Quarkus already produced a lean runtime, with the pipeline living inside a single process with well-defined boundaries. There were no hidden dependencies on the host, no fragile startup scripts, no tight coupling to the underlying machine.

Marta wrote a Dockerfile, wired a couple of environment variables, and that was… mostly it.

The hardest part wasn’t the application, but everything around it:

getting the right network access
aligning with security policies
making sure it could talk to the same external systems as before

So while most systems were being translated from one VM to another, Marta’s was quietly being repackaged.

And once it ran, something became clear:

It was still a monolith
Steps still called each other directly, in-process
The pipeline still lived entirely inside a single runtime

Only the execution environment had changed.

That was the first quiet lesson The Pipeline Framework taught the team: you can move where something runs without changing how it behaves.

A few weeks later, someone asked Marta how long her migration had taken; she hesitated (because the honest answer sounded wrong: “About a day. Maybe two, if you count the networking issues.”

Photo credit: Javier Mediavilla E, CC BY-SA 2.5 https://creativecommons.org/licenses/by-sa/2.5, via Wikimedia Commons

The Script That Refused to Stay Small

Mariano Barcia — Thu, 09 Apr 2026 21:54:41 +0000

It started, as these things often do, with a single process running on a single machine in a server room nobody liked visiting. The system took in shipment requests, enriched them with a few heuristics, and spat out routing hints. Nothing fancy, just enough logic to save operations teams a few hours a day, and Marta built it on her own as a side project.

Marta wasn’t new to Java, she had spent a few months working in a microservices project in Spring and liked the serverless functional-style thinking: small transformations composed together. She had enough scar-tissue by now having experienced the inevitable issues with Spring and wanted to experiment with Quarkus anyway.

She picked TPF because, on top of featuring a canvas UI to design the pipeline, she got the complete app's scaffolding as a pure Quarkus project. She could keep developing on her IDE as usual, only with the addition of the Quarkus environment plugin. And, she got to use Dev Services which she also wanted to try.

Her choices for the script were deliberately boring:

a JVM runtime (a single process) with
no high availability
a traditional direct method invocation between the orchestrator and the pipeline steps
no DB, just basic HTML responses to human queries

Each step in the pipeline was just a function. Input came in as loosely structured key/value data. No rigid schema, no upfront modeling, no SQL persistence.

She didn’t yet have to think about

execution tracking or audits
fan-out/fan-in logic
retry semantics
error handling
availability
high throughput
latency
integrations with 3rd parties
monitoring
security

And because she had started using AI-assisted coding tools, even the tests came almost for free, as TPF’s step isolation made it trivial to generate meaningful unit tests for each transformation.
It was fast. It was understandable. It worked and, crucially, it already had shape—even if nobody called it that yet.

But during one summer's day, a sandstorm from the Sahara impacted Valencia and caused temperatures to rise (a phenomenon called kalima). The A/C unit in the server room failed and, by the next morning morning, alerts were firing, CPUs were throttling, and someone mentioned, only half jokingly, the possibility of actual fire.

Architectural mobility for stronger software

Mariano Barcia — Tue, 07 Apr 2026 19:37:36 +0000

There’s a concept in sports science that’s easy to overlook because it sounds so basic: “mobility”. Mobility is defined as “the ability of a joint to move actively through its full, functional range of motion with control, stability, and strength“.

If you look at a simplified “athlete performance” pyramid, the foundation isn’t power or strength; it’s mobility. Everything else builds on top of that, but we spend most of our time discussing the upper layers and very little attention is paid to what sits at the foundation of the pyramid. Take away mobility, and the strength will falter.

       / - \
      /     \
     / Power \    Athlete Performance Pyramid
    /_________\
   / Strength  \  
  /_____________\
 /   Mobility    \ 
/_________________\

Now, the reasons why mobility is so important are many and complex, but basically have to do with how the nervous system is able to recruit muscle fibres, whilst at the same time staying healthy (ie. by doing “reciprocal inhibition”).

Putting aside the inherent complexity of the muscles in the human body, I think software systems behave in a similar way, and we spend most of our time discussing the upper layers:

scalability
throughput

whilst paying very little attention to what sits underneath all of that.

Most software systems miss something fundamental: they cannot change shape without breaking themselves.

You move from containers to functions → everything rewrites
You switch from REST to gRPC → contracts ripple through the system
You change how remote work is executed → business logic gets entangled

The system might be “strong” in its current form, but it lacks mobility. It’s rarely stated explicitly, and runtime, transport, and protocol are treated as the same decision.

You deploy to containers → you expose REST → you serialise JSON.
Or you go serverless → you wire HTTP → you pass payloads around.

Nothing looks wrong and in fact, it feels coherent, but still:

your execution model has dictated your transport
your transport has dictated your protocol
and all three together have dictated your system shape

This affects “architectural mobility” because

You cannot change where things run without rewriting how they communicate
You cannot change how they communicate without rewriting what they mean
You cannot evolve protocols without locking yourself into a runtime

That mobility is what allows your business logic to evolve regardless of any external infrastructure decision, and will allow you to make these deliberate choices:

do your workloads belong in containers?
do your workloads belong in serverless functions?
do they benefit from gRPC, or REST?

In The Pipeline Framework, architectural mobility is enabled by decoupling the transport from the execution platform from the runtime topology, like so:

                     Transport
               (LOCAL / REST / gRPC / Proto-HTTP)
                           ↑
                           │
                           │
                           │
                           │
                           │
                           ●───────────────→ Execution Platform
                          /                (COMPUTE / FUNCTION)
                         /
                        /
                       /
                      ↓
             Runtime Topology
  (Monolith / Pipeline / Modular)

Photo credit: https://unsplash.com/es/@weareambitious