DEV Community: Hideki Mori

The 3-line discipline

Hideki Mori — Mon, 29 Jun 2026 13:00:00 +0000

When I write code in unfamiliar territory, I write three lines, then I run it.

Then I write three more lines, and I run it again.

I've been doing this for twenty-four years. It's the most specific habit I have. I almost didn't write this article, because the habit feels too small to be worth describing — but then I noticed that it's the part of my way of working that I can never seem to explain to someone in real time. It needs writing down.

Three principles

The discipline rests on three things I believe about writing code. They're not deep. They've just stayed with me.

1. Trust nothing but your own code.

If you can't trust the code you wrote yourself, what can you trust? Not a library, not a vendor's documentation, not your own assumption from yesterday. The only thing in the system whose behavior you can fully verify is the code you just typed, by running it.

2. Write in code, not in language.

If you're describing what the code should do in Japanese or English, you're spending the same time you could have spent writing the code itself. By the time the code runs, the description is already done — by the code, in a more precise form than any language could give it.

3. Make three lines complete.

The three lines you just wrote should be complete. Error handling included. Validation included. Logging included. Not "I'll add validation later." Not "I'll wrap it in a try-catch later." Three lines, complete, then run.

(There's a small exception to this. Sometimes you do want to ignore every error and move on — for instance, when you're trying to understand whether the happy path works at all before you care about anything else. That's a different mode, used deliberately. It's not the same as "I'll handle errors later.")

Why three lines

Three lines is roughly the unit of thought I can hold completely. Five lines, and I start guessing what the third line did. Ten lines, and I'm reading the code as if it were someone else's. Three lines is the size that stays mine.

When three lines run and produce what I expected, I keep them. When they don't, I either fix them or delete them. The cost of deleting three lines is small enough that I have no attachment to keeping them.

What I'm protecting, by writing this small, is the alignment between the code in my head and the code that's actually running. When that alignment is intact, debugging is fast: I know which three lines just changed. When that alignment slips — because I wrote thirty lines without running them — debugging becomes archaeology. I'd rather spend the time in three-line increments and avoid the archaeology.

Components: write the caller, run, write again, run

When I introduce a new component into a system — a new library, a new vendor's API, a new framework — I don't start by writing the code that needs the component. I start by writing the code that calls the component.

The caller is small at first. Three lines. I call the component, I print what comes back, I run it. Then three more lines. I call it with different arguments. I print what comes back. I run it. Three more lines. I call it in a way that should fail. I see what failure looks like.

By the time I've spent an hour doing this, I know how the component behaves on the inputs I care about, how it behaves on edge cases, how it fails, what it returns when it fails. I have a small body of code that has tested the component from the outside, written in my own hand.

After that, the component almost never surprises me when I integrate it into the real work. It surprised me already, during the hour I was poking at it, and I noted what I learned.

This part of the discipline is what twenty-four years has changed about me the most. When I started, I would try to use a new library inside the real code right away, and then I'd be debugging both the library's behavior and my own use of it at the same time. I don't do that anymore. The library has to pass a small private interview first.

Even then, live data still surprises you

Here's the part that keeps the discipline honest: even when you've done all of the above, live data will still surprise you. The vendor's API will return something the documentation never mentioned. The status code will say success while the payload says something else. The same call you've made a thousand times will, on the thousand-and-first try, return data that belongs to a different question entirely.

I worked with a fairly mainstream translation API for many years. It's the kind of API most people in the industry have heard of. In day-to-day operation, the integration was stable. But in the operational record of how my code calls it, there are several places where I had to write defenses that aren't suggested by the documentation:

The languages endpoint, when asked for target languages, sometimes returned the response shaped like a source language listing. The HTTP status was 200. The JSON parsed. But a field that should be present on target languages was missing. The fix wasn't to escalate or to file a bug — it was to detect the mismatch in my code, log it as a retry-worthy condition, and call the endpoint again. The next call usually returned correctly.
Certain error messages from the API turned out to be retry-worthy, even though the HTTP status code didn't say so. A "Temporary Error" in the response body, or a "Tag handling parsing failed", both warranted retrying. I learned this not from the documentation but from watching the production logs over many months.

None of this is a complaint about the vendor. It's a mainstream API. The point isn't that it's flawed; the point is that any API run at scale, against real data, will produce these moments. The documentation is a description of intended behavior, not observed behavior. Observed behavior, in production, is always wider.

So even after the three-line discipline, even after the private interview with the component, the system goes into production and surprises me. Not catastrophically. Quietly. A condition I hadn't tested, behaving in a way I hadn't predicted.

I don't experience this as a failure of the discipline. I experience it as the part of the work that the discipline doesn't cover — and was never going to cover. The discipline brings me to the doorstep with my code in good shape. Live data is what's on the other side of the door, and it's not something I get to fully prepare for. It's something I respond to.

This is, I think, the part of the work I find most enjoyable.

Twenty-four years of this

I didn't set out to develop a discipline. I started writing software in 2002, at a company that was almost out of money, on a product that needed to ship in thirty days. There was no time to write thirty lines and then debug them. I wrote three lines, I ran them, I wrote three more. The shape of how I work formed itself in that situation, and it never went away.

What's changed over twenty-four years is what I do with the result. The three-line increments are the same. The "write the caller first, run, run again" is the same. The willingness to be surprised by live data is the same. What's deeper now is just the cumulative trust in my own code, and the cumulative humility about everything outside it.

If you write the code you can trust, you can carry the weight of everything you can't.

This is not what you should do. This is what twenty-four years has taught one specific person to do.

Built with Claude (Opus).

Earlier in this series:

Billing asynchronous work exactly once

Hideki Mori — Wed, 24 Jun 2026 13:00:00 +0000

Synchronous billing is easy, and that's the problem — it makes you think all billing is easy.

When a request does its work inline, the billable number is in the response by the time you send it. The gateway meters from there — the meter write, retries and all, is its problem, not yours. From your side, synchronous billing is one number in the response.

Asynchronous work breaks that. The request submits a job; the work happens later, in a worker; the result comes back through a poll or a callback. And the thing you bill for — characters processed, pages converted — isn't known when the request arrives. It's known when the job finishes.

So you can't meter at the edge. The meter has to fire from the completion path. And the real difficulty is firing it exactly once per unit of completed work — because requests, polls, and retries all conspire to make that zero times or many times.

This is platform-agnostic. Every submit-process-poll API has it. I'll use the system I run as the example, but the shape is the same anywhere.

Three ways metering goes wrong

On arrival. Carry the synchronous habit over and you meter when the job is submitted. But you don't know the size yet, so you're forced into a crude flat fee — or you bill for work that hasn't happened and might fail. Wrong unit, wrong time.

On retrieval. The subtle one. You wire the meter to fire when the client fetches the result. Now a client who submits a job, lets it run — costing you real money downstream — and never bothers to poll is never billed. You did the work for free. "Completion" is not "the client picked up the result." It's the worker finishing.

Without a fixed quantity. Input characters or output characters? Pages before OCR or after? If you haven't decided exactly what you measure and where, invoices drift and customers argue. Decide once; measure there.

All three point the same way: meter on measured work-completion, with a fixed definition of the unit. Not on arrival. Not on retrieval.

The mechanism: a durable outbox

In synchronous billing the gateway took the numbers off the response and metered them for you. Async takes that away: the numbers exist only in the worker, after the request has returned. So completion itself has to become a durable event.

The completion path writes a metering task — the job's measured quantities — into a durable outbox: a table that is the source of truth for what still needs sending. Something drains it, sends each task to the meter, records the outcome; a failed send stays in the table and is retried until it lands. (In my system a once-a-minute batch does the draining. The interval doesn't matter; the durability does.)

It has a name — the transactional outbox pattern — though it's the sort of thing you'd build without the name. And it is, exactly, the one rule the rest of the system already runs on: when the job finishes, report it reliably — retry as much as possible, return the result. Metering is just one more result that has to be reported reliably. I didn't build a billing system. I pointed the engine's own discipline at billing.

Exactly once = at-least-once × at-most-once

The outbox gives me at-least-once. A meter event is never silently dropped, because a failed send leaves the task in place to retry.

But at-least-once, on its own, double-charges. The classic failure: the send succeeds, the acknowledgement is lost on the way back, the task looks failed, the next run resends — and now it is counted twice.

So at-least-once needs a partner: an idempotent sink. Send the same meter ID twice, it counts once. That is at-most-once.

exactly-once = outbox (at-least-once) × idempotent sink (at-most-once)

Neither half is enough alone. I learned the second one the hard way — the same outbox-and-retry code, pointed at two different metering backends. One deduplicated on the ID and the numbers stayed clean. The other didn't, and the retries double-charged. Same mechanism, different sink, different bill.

So the thing worth writing down isn't "this platform guarantees idempotency." Platforms change. The durable statement is: this pattern requires an idempotent sink. If yours doesn't deduplicate, your retries are a liability, not a safety net.

Bill on success, and survive retries

Two more places it bites.

Success, not completion. Fire the meter on successful completion — not on "the job reached a terminal state." A failed job must not emit a billable event. Wire it to the wrong terminal state and you charge people for errors, then spend your week on refunds.

Partial failure. What you bill on a half-finished job depends on whether half a result is worth anything. A text extraction fans out into many independent calls; if nine of ten succeed and one fails for good, you bill the nine — the successful work has standalone value. Document conversion is the opposite: a file that converts eight of ten pages and then dies isn't eighty percent of a document, it's a corrupted one. No charge, nothing returned. Bill at the granularity where partial output has value.

Retries. The engine retries aggressively — that is the point of it. Meter per attempt and every retry inflates the bill. So the meter is per successful job, fired once — which is exactly what the outbox and the idempotent sink already guarantee. It is not extra work; it falls out of the same design.

It all reduces to one sentence: the billable event is one successfully-completed unit, counted once.

The shape

In synchronous billing the meter is a property of a request arriving. In asynchronous billing it is a property of work finishing — and the discipline is firing it exactly once per successful unit.

It is worth separating what is hard from what is free. The completion wiring — the outbox, the retries — is yours to build. The at-most-once half is the sink's job, if you chose a sink that does it. Get both, and a client polling ten times, a worker retrying five, and a job that half-failed all resolve to the right number of credits.

That is the whole thing. It isn't much once it's drawn — but every line of it is a place I have watched a bill come out wrong.

Built with Claude (Opus).

Write the code well once, the spec stops bothering you

Hideki Mori — Mon, 22 Jun 2026 13:00:00 +0000

I wrote a Java class twenty years ago that assembled tar archives on the fly. It ran for fifteen years. In that fifteen years, nobody touched it. Not me, not anyone else.

This is a story about why.

The hundred storefronts and the one carrier spec

In the mid-2000s, I was running a content distribution platform. Over a hundred storefronts plugged into it. Bookstores, label-branded stores, carrier-branded stores. Each one resold the same underlying content — books, comics, music, video, and more — but with their own branding wrapped around it.

Among those hundred-plus storefronts, a few dozen of them shared a particular delivery spec — one of the major Japanese carriers had pinned down a specific shape for downloadable content on their old mobile phones. The content had to arrive as a tar archive. The phone would fetch it using HTTP Range Requests, byte ranges at a time, often resuming after a dropped connection.

The format was the same for all storefronts on that spec: a tar archive containing a known set of files, in a known structure. The files inside were not the same. Each storefront wanted its own branding image, its own store name in the metadata, its own thumbnail. The wrapper format was fixed. The contents were per-storefront, per-product.

A few dozen storefronts asking for the same shape with different contents, multiplied by the catalog. It was a combinatorial problem.

What I didn't do: pre-generate

The obvious approach was to pre-generate the tar archives. For each storefront, for each product, produce the archive once, write it to disk, serve it from there.

I rejected this almost immediately.

Storage isn't free. Number of storefronts times number of products times the size of each archive. The math wasn't terrible at the time, but the moment any storefront changed its branding — a new logo, a new store name, a new image — every archive associated with that storefront would be invalidated. Every product, every catalog entry. I'd be re-running the bake of tens of thousands of archives because someone tweaked a string.

I thought about this for a while and then stopped thinking about it. The shape that came out the other side was different.

What I did: deterministic generation at request time

I generated the archive at the moment of the request.

For each incoming download:

Look up the product. Find the raw content.
Look up the storefront. Find the branding config: the store name, the image to embed, the thumbnail.
Assemble a tar archive in memory, with that store's content wrapped around that product's data.
Stream the result to the client.

The archive didn't exist before the request arrived. It didn't exist after.

The CPU cost was real but small. Application servers were cheap and easy to scale horizontally. Storage was scarce and combinatorially expensive. The trade was obvious to me.

But there was one detail that made the whole shape work — and without it, the rest would have fallen apart.

The mtime had to be fixed

HTTP Range Requests assume the resource is stable. The client says give me bytes 0 through 8191, you give them those bytes. Later the client says give me bytes 8192 through 16383, and the bytes you give now have to be the second half of the same file the client started downloading. If they're not — if the file changed between the two range requests — the client ends up with a corrupted archive.

A tar header has a field for modification time. Every file inside the archive has an mtime — twelve bytes of octal-encoded Unix timestamp.

If I generated those mtimes from the current clock at the moment of header creation, every regeneration would produce a different archive. Even though the content was identical. Even though the structure was identical. Just the timestamps would shift, and Range Requests would break.

So the mtime had to be deterministic. The same archive had to come out every time, regardless of when the request arrived.

I fixed it to the product's update timestamp:

mtime = product.updateDate.getTime() / 1000L

That timestamp changed only when the underlying product was updated by an operations colleague. Between updates, every tar archive for that product was byte-identical, regardless of how many times it was assembled.

The natural follow-up question is: what about an update that lands mid-stream, while an archive is being assembled? The source files for each product were versioned. A product update produced a new version of the source set, not an in-place rewrite. An archive being assembled never saw a half-updated set of source files; it saw a consistent version, from start to finish.

Range Requests worked. Resumes worked. The phone could disconnect at byte 5000 and reconnect for bytes 5001 onwards from a different application instance entirely. The bytes would line up.

The archive existed only at the moment of the request, but it was deterministic to the last source update.

Fifteen years of nobody touching it

I wrote that class in 2006. The platform ran on it for the next fifteen years.

In those fifteen years:

New storefronts were added. Config rows in a database. No code change.
New products were added. New files on disk in a known structure. No code change.
New storefronts wanted different branding images. They uploaded different images. No code change.
The product update flow was tweaked many times. The mtime convention held. No code change.

Nobody re-wrote it. Nobody refactored it. Nobody patched it. It just kept assembling tar archives.

The on-call queue never had an alert about it. The maintenance docs never had a runbook section for it. New engineers never asked about it, because there was nothing to ask.

The spec stopped bothering anybody.

What I was actually choosing

When I picked dynamic generation over pre-generation, I wasn't really picking CPU over storage. I was picking where the complexity would live.

If you pre-generate, the complexity lives in the data. Every change in input — branding, content, metadata — has to propagate into a regeneration of the materialized output. The complexity is distributed across the storage layer, and someone has to maintain the regeneration pipeline.

If you generate at request time, the complexity lives in one piece of code. That code is hard to write well the first time. There's a tar format to understand. There's a deterministic mtime requirement that's easy to miss. There's the Range Request semantics. But once that code is written well, the system has no other place where the complexity is stored.

And then nobody has to touch it.

This is the trade I keep coming back to, twenty-four years into writing software alone. If you write the code well once, the spec stops bothering you. The work you did at the start absorbs all the work you didn't have to do later — by you, or by anyone else.

Twenty-four years of the same choice

I'm still doing it. The platform I run now is built on the same pattern at a different scale: a hundred-plus vendors of OCR, translation, and other document services, all behind a small set of public APIs that compose them dynamically per request. There's no pre-generated catalog of vendor combinations. There's one piece of code that knows how to wrap one vendor in one shape, and a configuration system that lets new vendors plug in.

I expect the same fifteen-year quiet that the tar archive code got. It's not that I'm confident. It's that I've made the choice often enough to know what it usually leads to.

This is not what you should do. This is what twenty-four years has taught one specific person to do.

If you write the code well once, the spec stops bothering you. Most of what I do, I do for that.

Built with Claude (Opus).

Earlier in this series:

Two patterns, five services, one n8n workflow

Hideki Mori — Wed, 17 Jun 2026 13:00:00 +0000

The first two articles in this series each showed one technique. Implementation notes #001 was a dynamic dropdown — a form field that fills itself from an API. Implementation notes #002 was a dynamic credential — an API key that arrives from the form and threads through to the HTTP nodes.

This article is the capstone. It walks through all-services-demo, the example workflow that ships with n8n-nodes-ldxhub, where those two techniques combine with a Switch node to host five different AI document-processing services inside one workflow — structured extraction, translation refinement, OCR, PDF conversion, and text extraction.

The screenshots and the workflow JSON below come from the n8n-nodes-ldxhub package. The patterns themselves are generic — they work for any set of services you want to consolidate into a single template.

This is not a "follow these steps" article. It's a parts catalog. No two readers are solving the same problem, and templates rarely fit anyone's situation as-is. Take what fits. Drop the rest. You don't need to understand all 46 nodes to reuse the patterns.

The shape

The workflow has 46 nodes — large enough to look intimidating in the editor, but structurally it's just five repeated paths plus a small routing section.

The entry section is two nodes:

On form submission — the trigger. Asks the user which service they want and collects an API key.
Route by Service — a Switch node with five outputs, one per service.

Everything to the right of the Switch is service-specific. Five paths fan out: StructFlow, RefineLoop, RenderOCR, CastDoc, ExtractDoc. Each path ends in two Form Ending nodes — one for success (auto-downloads the result), one for error.

That's the spine: form → switch → service path → ending. The complexity is pushed into the service paths.

The spine: routing by static comparison

The Switch node ("Route by Service") uses Rules mode. Each rule reads the same expression from the form — {{ $json.service }} — and compares it to a static service name.

Rule 1:  {{ $json.service }}  is equal to  structflow   → output: structflow
Rule 2:  {{ $json.service }}  is equal to  refineloop   → output: refineloop
Rule 3:  {{ $json.service }}  is equal to  renderocr    → output: renderocr
Rule 4:  {{ $json.service }}  is equal to  castdoc      → output: castdoc
Rule 5:  {{ $json.service }}  is equal to  extractdoc   → output: extractdoc

The read side is dynamic (the expression resolves to whatever the user picked). The match side is static (fixed strings). That asymmetry is intentional. Static rules mean adding a new service is a manual edit — open the Switch node, add a row, save. No regeneration, no template hooks, no auto-discovery. Boring and unsurprising.

This is the part you can lift cleanly: a Switch with N static rules driven by one expression from upstream. It works for service routing, document type routing, user tier routing, anything that fans into discrete branches.

Two patterns inside

Once you start reading the service paths, you notice something: they are not all the same shape. There are two distinct patterns.

Pattern A: single-step form (StructFlow, RefineLoop — 7 nodes)

Get Models (HTTP)
  → Derive Options (Set)
    → Run Form (Form, next page)
      → Inject Binary (Code)
        → Run (LDX hub)
          → Download / Error (Form Endings)

One form page collects everything the user needs to choose. The model selection, the input, the parameters — all in one screen. There's only one form page after the Switch.

Pattern B: cascading multi-step form (RenderOCR, CastDoc, ExtractDoc — 10 nodes)

Get Engines (HTTP)
  → Select Engine (Form, next page)
    → Derive Options (Set)
      → Upload File (Form, next page)
        → Filter by File (Set)
          → Select Output (Form, next page)
            → Inject Binary (Code)
              → Run (LDX hub)
                → Download / Error (Form Endings)

Three form pages, each gated on the previous one. First the engine is chosen. Then the file is uploaded. Then the output format is selected — and the available outputs are filtered based on what the chosen engine supports for the uploaded file type. The Filter by File Set node sits in the middle of that dependency.

Why two patterns, not one

The shape of the path follows the shape of the user's decisions. When the choices are independent — pick a model, pass some data — one form page is enough. When the choices cascade — engine restricts file types, file restricts output formats — the form has to be split, and intermediate Set nodes have to filter the options between pages.

I tried to force a single pattern across all five services. It made the simpler services more complicated than they needed to be. The honest design was to let the cascading services be longer, accept the asymmetry, and document it.

Two patterns isn't a sign of incompleteness. It's the consolidation accepting that two shapes were genuinely warranted.

Anatomy of one path

Walking through StructFlow gives you the vocabulary for all five paths. The other four are variations.

Get Models — an HTTP node that hits /structflow/models and returns the available LLMs (gpt-5.5, claude-sonnet-4-6, gemini-3-flash, etc.). This is the data source for the dropdown.

Derive Options — a Set node that reshapes the model list into the format n8n's Form trigger wants for a dropdown: [{name, value}, ...]. Same trick as in #001 — derive the dropdown from data, not from a hardcoded list.

Run Form — a single form page that asks for everything: which model to use, the input data, any parameters. The "model" dropdown reads its options from the upstream Derive Options node.

Inject Binary — a Code node that does one thing. In n8n, uploaded files travel through the workflow as binary data, separate from the JSON fields, and some intermediate nodes (like Set) only preserve the JSON side. By the time data reaches the LDX hub node, the binary part has been dropped.

return $input.all().map(item => ({
  json: item.json,
  binary: $('StructFlow: Run Form').item.binary
}));

The Code node reaches back to the form node and re-attaches the binary. One line of glue, but without it the file disappears.

Run — the LDX hub custom node, with runJob: structFlow. This is where the API call actually happens. The credential is set in expression mode to read from the form input — the dynamic credential pattern from #002.

Download / Error — two Form Ending nodes. The Run node has two output ports: Success goes to Download (which serves the result file), Error goes to Error (which shows the error message).

Five other paths follow the same idea. The names change, the number of form pages changes, but the role of each node is the same.

The convergence: five paths, one node

All five service paths end at the same LDX hub custom node. Same node type, same credential, same shape — only the runJob parameter differs:

StructFlow: Run    →  runJob: structFlow
RefineLoop: Run    →  runJob: refineLoop
RenderOCR: Run     →  runJob: renderOcr
CastDoc: Run       →  runJob: castDoc
ExtractDoc: Run    →  runJob: extractDoc

This is the abstraction the custom node provides. From the workflow's perspective, "running a service" looks identical across the five paths. The differences are buried inside the node's implementation, where they belong.

This generalizes the idea from #002's sidebar: a custom node that hides its variations behind a uniform interface lets you compose it freely. Five services. One credential type. One node. Five jobs. The workflow author doesn't have to know how StructFlow differs from RenderOCR — the node knows.

If you're building your own custom node, this is the shape worth aiming for. One node, parameterized by job kind. The workflow stays clean. The variations stay encapsulated.

The if/else pair: error endings

Every service path has two endpoints: Download (success) and Error. Both are Form Ending nodes. Both are visible to the user. This isn't decorative.

A distributable template has one minimum obligation: once the user clicks Submit, they need to see what happened. If the call succeeded, they get the result. If it failed, they get the error. There's no third state where the form just ends silently.

Earlier failures — the Get Models call returning empty, the Inject Binary node crashing — are not handled. Those are skipped here because the template is meant to be minimal, and because adding error endings everywhere makes the canvas unreadable. But the final Run node's error branch is mandatory. That's the one place where the user's expectation ("I started a job, what happened?") has to be answered.

Where there's an if, you need an else. The else doesn't have to be elegant. It just has to exist.

This is the part you can lift on its own: any time a workflow has a user-visible "run" step, pair its success with an error ending. Other branches can be skipped or logged, but the user-facing one is non-negotiable.

What consolidation looks like

The technique parts above — Switch routing, two form patterns, Binary injection, Run convergence, if/else error pairing — are each portable. You can lift them one at a time. But the article would be missing something if it stopped there.

Bringing five services into one workflow is itself the work. Not a tutorial-friendly kind of work, because nothing in this section is a discrete technique. It's a series of small decisions:

Choosing which five services to include (not all of them — five is enough to demonstrate, more would clutter).
Standardizing the node naming across paths (<Service>: <Role> everywhere — every reader knows where they are).
Accepting that the two patterns are real, and not forcing every path into the same shape.
Putting the differences inside the form pages and inside the Run node's runJob parameter — the spine stays uniform.
Designing the convergence: every path ends at the same node type, so adding a sixth service later is a copy-paste-edit, not a redesign.

None of these are clever. Each is the obvious decision once you've seen the alternatives. But the obvious decisions are what hold the template together.

There's a particular kind of reader this article is also for: the one who doesn't need the technique, who just needs a working template they can drop into n8n and run. The consolidation work is the deliverable for them. The fact that the article also explains how it works is a side benefit.

This contrasts with a different design philosophy — the one that spreads concerns across many separate sub-workflows, each handling a narrow responsibility. In larger n8n installations with several maintainers, you might split these responsibilities into reusable sub-workflows, with each service called via the Execute Workflow node. For a solo-maintained distributable template intended to be lifted and adapted, the consolidated shape was easier to understand and ship. Fewer moving parts, fewer integration points, one place to read.

Closing

This is parts.

If you read this article and take the whole workflow, run it as-is, that's fine. If you take only the Switch routing and rebuild every service path from scratch, that's better in many cases. If you take only the Inject Binary trick because that's what bit you yesterday, that's the best use of this article.

No two requirements are identical. Every reader is solving a different problem. A template that pretends to be a one-size answer would be lying. A template that is honest about being a parts catalog — here are the pieces, here is how they fit together, take what fits — is a different kind of useful thing.

That's what all-services-demo is meant to be. That's what this article is meant to be.

The n8n-nodes-ldxhub package ships examples/all-services-demo.json alongside the node code. Import it into your n8n instance, add an LDX hub API key (free tier: 25,000 credits/month, no card), and the workflow runs. Open the JSON and lift parts into your own templates.

This closes Phase 1 of Implementation notes — three articles, three angles on the same theme: how an n8n workflow becomes a small, distributable thing. The next phase will pick up other corners worth writing down.

Twenty four years, ten DB migrations, zero downtime

Hideki Mori — Mon, 15 Jun 2026 13:00:00 +0000

Twenty four years. Ten DB migrations. Zero downtime.

Except the first one, where I lost seven minutes I couldn't accept.

That seven minutes is why this article exists.

The seven minutes

It was in the mid-2000s. I was running a content distribution system on my own, with a small open-source database underneath. The platform was growing, and at some point we decided to move to a much larger commercial database — an appliance-grade one, the kind you specify by line of business and not by hostname.

I planned the switchover for a thirty-minute maintenance window. I did the work. End-to-end, it took seven minutes.

Seven minutes during which the service was down. End users couldn't reach the catalog. Bookstores couldn't sync. Publishers couldn't see their numbers.

It bothered me more than it should have. The migration was a success. The system came back up. Nobody complained.

But it had been down. Seven minutes that, on paper, the agreement said was acceptable. Seven minutes that, in my head, I never wanted to repeat.

That feeling didn't go away. I started designing every database operation from that day as if seven minutes was the wrong answer.

The contract no one made me write

That platform delivered books, comics, and music — content from publishers and labels through the bookstores that resold it. End users, bookstores, publishers, label owners: all of them sat on top of a single piece of plumbing I was responsible for.

There was no formal SLA written anywhere that said "this never goes down." But there was something stronger than an SLA: a sales-side expectation. Inside the company, it was assumed the service was always reachable. Customers were sold on the assumption that downloads worked at any time of day. Bookstores integrated against that assumption. Publishers settled royalties on top of it.

If I took the service down for an hour, none of those agreements would have technically been broken. But the silent contract — you never notice me running maintenance — would have been.

Once, before a particularly large migration, I had to brief one of the major carriers (they were on the bookstore side, technically a B2B customer). We met around a whiteboard. I drew the sequence. After about five minutes, the lead engineer on their side just nodded and said something like, "okay, if you're doing it, we're fine." We didn't need a recovery plan from them. We didn't need a coordinated test window. They didn't even update their monitoring.

That trust didn't come from documentation. It came from the fact that none of the previous migrations had touched their integration.

So the shape of how I do these migrations started with seven minutes I couldn't accept, and was kept alive by twenty-three years of not breaking that quiet contract again.

The shape

Here is the shape, stripped of vendor names. It is not new. It is not clever. It has just survived.

Step zero: separate the data into two kinds.

Data A: anything the end user reads. This is what the service actually serves. If this is wrong or unavailable, the service is wrong.
Data B: aggregates, summaries, derived tables, everything else. Batches write to it. End users never read from it directly.

The rule for Data A is: real-time synchronization, both old and new databases, no exceptions. The rule for Data B is: batches can stop for a while, you'll catch up later.

Step one: well before the migration window, set up two batches that incrementally copy Data A and Data B from the old database to the new one. Use the last-modified timestamp on each row. Take physical deletes into account by occasionally diffing the row sets and removing what's no longer there. Run these for days or weeks until the new database is essentially a copy of the old, plus or minus the most recent few minutes.

Step two: at migration time, stop the batches that write Data B. Run the Data B copy one last time. The aggregate tables on the new database are now identical to the old.

Step three: switch the application logic to a maintenance mode where Data A is written to both databases, but read only from the old one. Every user-facing update now produces two writes: one to the old database (the authoritative one), one to the new database (best effort, the eventually-authoritative one). If the write to the new database fails, it's swallowed — step four catches the drift.

Step four: once all instances of the application are in this dual-write mode, run the Data A copy one final time. This catches anything that was written to the old database between the last sync and the dual-write switchover. After this, both databases agree.

Step five: switch the application logic to read from the new database, while still writing to both. This is the moment of truth. If anything is wrong with the new database, this is when the user feels it.

Step six: switch the application logic to read and write to the new database only. The old database is detached.

For a migration (the new database stays), the batches that write Data B can now resume against the new database, and you're done. For a maintenance bypass (the old database is coming back), you do the same sequence in reverse, and the old database returns to service.

For reference, here's how the application behaves at each step:

Step	App writes	App reads	What happens
0	—	—	Classify rows into Data A and Data B
1	old	old	Incremental copy batches running
2	old	old	Stop Data B batches, final Data B copy
3	old + new	old	Dual-write switchover
4	old + new	old	Final Data A sync
5	old + new	new	Read switchover
6	new	new	Old database detached

The thing nobody talks about: mixed states

This shape works because each step is resilient to mixed states.

I deploy applications manually. I have for twenty-four years. There is no coordinated rolling restart, no atomic feature flag flip across all instances. When I switch the application logic to dual-write mode in step three, some instances are still in single-write mode (against the old database only) while others are already in dual-write mode. That mixed state can last as long as it takes me to walk through each server.

The shape is designed so that mixed states are correct.

When step three is rolling out: some instances write to old only, some write to both. All instances read from the old. The old database stays authoritative. Reads are consistent.

When step five is rolling out: some instances read from old, some read from new. By this point both databases agree (step four just synced them). Either read is correct.

When step six is rolling out: some instances still dual-write, some write to new only. All instances read from new. The new database is authoritative. The few writes that still hit the old database are harmless — it'll be detached momentarily.

I don't have to wait for a deployment to finish. I don't need a feature flag system to coordinate it. I don't need a service mesh to make it safe. I need the property that the shape stays correct while it's transitioning.

This is the part of the design that is older than every operational tool I see today. And it's the part I haven't found a reason to replace.

Rollback was never a special case

If you'd asked me five years ago whether this design has rollback, I would have said yes, of course. The reverse sequence is the rollback.

A maintenance bypass already runs forward, then backward. That backward leg is rollback. It's executed every single time. Rollback isn't an emergency path. It's a normal part of the workflow.

I've done this kind of migration over ten times in twenty-four years. I have never had to use the reverse sequence as an emergency. Not because nothing ever went wrong. But because the preparation phase — the days and weeks of incremental copying, of double-checking the deletes, of staring at row counts — catches the things that would have gone wrong, before they can.

The boring part of the work is what makes the dramatic part of the work disappear.

Twenty four years later

I'm going to write something now that should probably embarrass me but doesn't: I enjoy this work.

A new database to move into — especially a serious appliance-grade one — is one of the most enjoyable things I get to do. The preparation is meditative. The cutover itself is short and quiet. The week after, when the system is running on the new hardware and the end users have noticed nothing, is satisfying in a way I have not gotten from any other kind of engineering.

Twenty four years. Ten migrations. Zero downtime, after the seven minutes I couldn't accept.

That's the entire story. There are other databases out there now, other appliances, other ways of doing this. There are managed services that do most of the dance automatically. There are tools that take a lot of the carefulness off your hands.

I don't have an argument against any of those. I just know what survives in my hands: a separation of data into two kinds, a dual-write window in the middle, a resilience to mixed states, and a reverse sequence I always treat as ordinary.

This is not what you should do. This is what twenty-four years has taught one specific person to do.

Built with Claude (Opus).

Earlier in this series:

Let your n8n template ask for the user's API key

Hideki Mori — Wed, 10 Jun 2026 13:00:00 +0000

You built a workflow worth sharing — and it works perfectly. Until someone else imports it.

The bottleneck is the API key. Use yours, and every user is billed against your account. Use theirs, and they each have to find the credential UI, paste their key, and reconnect every time. Both are friction. The cleaner option is to let the workflow ask for the key on the form, then thread it through to the HTTP nodes that need it. It's simpler than it sounds.

This post walks through the pattern with a working credential setup, an alternative for single-node simple cases, the gotchas, and a note on what this enables for custom node authors.

The screenshots below come from n8n's built-in Bearer Auth credential and from the n8n-nodes-ldxhub package's own credential schema. The technique itself is generic — what's shown here works for any HTTP-node workflow and any custom node that supports expression-mode credentials.

The form asks, the credential listens

The simplest case: a Form Trigger collects an API key, then an HTTP node hits an authenticated endpoint with that key. Two nodes, one bridge between them — but the bridge isn't a direct expression. It runs through a credential.

The flow:

Form Trigger collects api_key (use the Password element type for masking)
A Bearer Auth credential references that form input via expression
HTTP node picks the credential

The Form Trigger is straightforward. Add one field:

Form Trigger
  Form Fields:
    - Label: API Key
    - Element Type: Password
    - Custom Field Name: api_key
    - Required Field: yes

Element type matters. Use Password instead of Text and the input gets masked on screen — the key isn't readable to someone glancing at the browser.

Here's the rendered form a user sees when they open the workflow URL:

Wiring the credential to expression mode

For a Bearer token (which is what most modern APIs use), create a new credential of type Bearer Auth — a generic credential built into n8n that's purpose-built for Authorization: Bearer ... headers. It has a single field:

Bearer Token: YOUR_API_KEY

Click the small fx (or =) toggle next to the Bearer Token field to switch it into expression mode. Then replace the value with a reference to the form's input:

Bearer Token: ={{ $('On form submission').item.json.api_key }}

The = prefix tells n8n this is an expression, not a literal string. Everything inside {{ }} is JavaScript, and $('Node Name').item.json.field reaches across the workflow to grab a value from another node — the same long-form reference pattern from Implementation notes #001. The Bearer Auth credential automatically prepends Bearer to the token at send time, so you don't write the prefix yourself.

Save the credential. You'll see this:

[ERROR: No path back to node]

That's display-only. The credential edit UI has no workflow execution context, so it can't resolve the expression at that moment. When an HTTP node later invokes this credential from inside a running workflow, the expression resolves correctly.

This is worth pausing on, because many people stop here. They assume the credential is broken and abandon the technique. It isn't broken. Save it anyway. Run the workflow. The key flows through.

A note on the error text: Different credential types show slightly different display-only messages for the same situation. The Bearer Auth credential shows [ERROR: No path back to node]; some custom-node credentials show [ERROR: Referenced node doesn't exist]. Same root cause (no workflow context at edit time), same harmlessness — just different wording depending on the credential implementation.

A note on credential type choice: Bearer Auth uses the standard Authorization header. If your target API expects a different header name — X-API-Key, X-Custom-Auth, etc. — use Header Auth (custom Name/Value) or Custom Auth (full JSON-shaped headers) instead. The expression-mode technique works identically for all of them.

Using the credential in an HTTP node

Configure the HTTP Request node to use the credential:

HTTP Request
  Authentication:    Generic Credential Type
  Generic Auth Type: Bearer Auth
  Credential:        <your credential name>
  Method:            (whatever the API needs)
  URL:               (the endpoint)

The HTTP node now sends Authorization: Bearer ... with the value filled in from the form. No hardcoded keys. No per-user credential setup. The workflow asks, the user types, the request goes out.

You can drop in as many HTTP nodes as the workflow needs — every one of them references the same credential, so the key only has to be entered once on the form, regardless of how many endpoints get called downstream.

Alternative: skip the credential entirely

For a workflow with one HTTP node, you can short-circuit this. Set Authentication: None on the HTTP node and write the header directly:

HTTP Request
  Authentication: None
  Headers:
    - Name:  Authorization
    - Value: =Bearer {{ $('On form submission').item.json.api_key }}

This works. It's faster to set up. It's worth knowing.

What it doesn't give you:

Reuse across multiple HTTP nodes in the same workflow
A path to custom nodes that expect credentials (more on that below)
The mental separation between "this is auth material" and "this is request data"

Use it for one-off prototypes. For published templates with more than one authenticated call, the credential approach scales better.

Three things to watch out for

1. The display-only error has different wording per credential type

Already covered above — the credential edit UI has no execution context, so it can't resolve the expression at design time. Save it, run the workflow, the expression resolves. What's worth noting is that the message itself differs by credential type:

Bearer Auth, Header Auth, and most generic credentials show: [ERROR: No path back to node]
Some custom-node credentials (the LDX hub Dynamic credential below, for instance) show: [ERROR: Referenced node doesn't exist]

Both are display-only. Both go away at runtime. Don't let the wording trick you into thinking one credential type is more broken than the other.

If you actually have a typo (wrong node name in the expression), you'll see the same error message at design time — same display, different cause. The only way to distinguish a display-only error from a real one is to run the workflow and look at the outgoing request.

2. The `Password` element type controls masking, not security

The Password element type on the Form Trigger masks input on screen. It doesn't encrypt anything, doesn't store the key separately, and doesn't hide the key from n8n's execution logs. Anyone with access to the workflow's execution history can see what was sent.

Treat masking as a courtesy to the user (so the key isn't readable over their shoulder), not as a security boundary. If you need stronger guarantees, the key needs to live in a properly stored credential — and at that point you're back to per-user credential setup, which defeats the form-based approach.

This pattern is convenience-oriented, not secret-management-oriented. For genuine secret handling — vault integration, audit trails, key rotation — n8n offers external vault support on its Enterprise plan. For everything else, the form-based pattern is a UX optimization, not a security upgrade.

3. Credentials are global, expressions are runtime-scoped

There's a slightly odd structural fact behind this pattern: the credential record itself isn't tied to any specific workflow — n8n stores credentials globally, and any workflow can reference one. But the expression inside the credential references a specific node by name ($('On form submission')), which can only resolve inside a workflow execution context.

The credential is global. The expression inside it is workflow-scoped. At edit time, those two worlds are disconnected. At runtime, n8n binds them together — but only if both halves match.

This is also why a credential built around one template's node names can fail in a different workflow that doesn't have those nodes. The mismatch is silent until the workflow runs.

Either standardize your trigger node names across templates (always On form submission), or create a separate credential per template. If you're publishing several templates that each ask for an API key, having one credential per template is the cleaner long-term shape — credentials are cheap, mismatches are expensive.

Everything above applies to standard HTTP-node workflows. The next section is about something broader: how custom nodes can participate in the same pattern, and what that means for n8n's community ecosystem.

When a custom node also supports expression credentials

Most discussions of dynamic credentials stop at the HTTP node pattern above. There's a second class worth knowing about: custom nodes (community-built, like n8n-nodes-asana or n8n-nodes-ldxhub) that define their own credential types. They don't use HTTP node headers — they read from the credential directly. Which means the form-to-credential pattern needs to be supported by the node itself.

A custom node that anticipates varied use cases lets the user choose between two modes for the same credential:

Static mode — traditional credential setup:

Key stored directly in the credential
One-time setup per user
Best for personal/internal workflows

Dynamic mode — same credential, key field in expression mode (={{ $('On form submission').item.json.api_key }}):

Key resolved from form input at runtime
No per-user setup
Best for distributable templates

Same credential type. Two usage patterns. The user picks based on what they're doing.

Note that only the API Key field is in expression mode here — the Base URL is left as a static https://gw.ldxhub.io. You could put the Base URL in expression mode too (and the all-services-demo template in the LDX hub package does exactly that, asking the user for a host on the form). For this article's example we keep it simple: one moving part, one expression.

For node authors, the takeaway is: design your credential schema to support expression-mode values from the start. Don't hardcode a regex validation that rejects {{ }} syntax. Don't fail on empty initial values (the expression resolves at runtime, not at credential save time). Don't insist on a particular key format if the value will be computed from somewhere else.

A node that works in both modes is useful in twice as many contexts — personal automation and template publishing — for the cost of letting the credential field be an expression. That's a low investment with broad payoff.

Why this matters

The default n8n workflow is a one-account thing. You build it to call APIs against your own credentials, save it, and it runs for you. Anyone who imports it has to either match your account exactly or rewrite the auth.

Dynamic credentials change this. The same workflow now adapts to whoever runs it — their API key, their account, their bill. The template becomes a small application that anyone can pick up.

Together with dynamic dropdowns (Implementation notes #001), this is the second piece you need to ship a workflow that's actually distributable. The form asks for a key. The credential threads it through. The HTTP nodes — or compatible custom nodes — make calls. No setup ceremony, no account juggling, no copy-paste of credentials from configuration page to configuration page.

The complete reference workflow

The all-services-demo example in the n8n-nodes-ldxhub package ships with this pattern. The Form Trigger asks for an API key and a host. Dynamic credentials thread both into five different service paths, each using the LDX hub custom node with expression-mode credentials. Inspect examples/all-services-demo.json to see the credential setup and the node calls that consume it.

For a free LDX hub key to run the demo, head to gw.portal.ldxhub.io — 25,000 credits per month, no card. Or take the credential pattern and apply it to any API you want.

Closing

The credential-with-expression pattern is one of those n8n techniques that's both completely sanctioned by the design and never quite documented as "this is how you ship templates." It just sits there, in the small fx toggle next to every credential field, waiting for someone to flip it.

For node authors, designing for expression-mode support from day one costs almost nothing. For workflow authors, it's the difference between "here's my template, please configure four things to use it" and "here's the form, paste your key."

The boring part is that there's almost nothing exotic happening. The mechanism was already there. The missing piece was realizing that credentials didn't have to belong to the workflow author.

Abstractions are fine. Starting on them isn't.

Hideki Mori — Mon, 08 Jun 2026 13:00:00 +0000

I've been writing software alone for 24 years. The shape of how I do that hasn't changed much — but I've watched the environment around me change a lot, and one shift has been quietly bothering me.

It's the shift in what application engineers are given on day one.

Pain used to teach you when something was wrong

In the old days, the lesson was simple. Your hardware stopped responding. That was the lesson.

A box couldn't keep up — you saw it on the dashboard, you felt it in the user complaints. You learned, often the hard way, that you needed an LB and two machines instead of one. The pain told you the system had outgrown its current shape.

EC2 didn't change this much. An instance could still get pinned at 100% CPU. The application could still hang. The pain was still there, just on rented hardware instead of bought hardware. The lesson — squeeze whatever you can out of the application layer first — was still delivered in the same form.

The pain was the cheapest monitoring tool any of us ever had.

Serverless took three pains away

Then serverless arrived. Auto-scaling. Pay-per-use. Managed everything. And without anyone really announcing it, three things that used to teach engineers stopped teaching them.

Pain 1: cost spikes that show up too late

In a per-use billing model, your application can be running badly for weeks before the financial signal arrives. You only notice when the invoice shows up at the end of the month — by which point, the failure is already paid for.

The "fix" most people reach for is a budget alert. But a budget alert is a smoke detector after the fire is already in the wall. You needed to know in week one, not in week four.

Modern anomaly-detection tools can shorten the gap from weeks to hours. They help. But notice the framing: each new tool exists because something underneath was hidden in the first place. The tool is a patch on a layer of invisibility, not a substitute for not having that layer.

Pain 2: performance degradation that auto-scaling hides

You're looking at a database load graph that's been climbing for three months. Why?

Is it because users are growing? Healthy. Or is it because your aggregation table is missing partitions, so query cost grows superlinearly with data volume? Not healthy.

When the database has fixed limits, this question gets forced on you. The database starts complaining. You have to look.

When the database auto-scales, the second condition is much easier to overlook. The infrastructure absorbs the inefficiency, and nothing forces you to look. The graph keeps climbing. The bill keeps climbing. Nobody traces it back to the actual code that's doing the wrong thing.

Pain 3: where the work actually happens

This is the one I think about most.

Someone I work with recently described a problem to me like this: the managed GraphQL layer is firing way too many SQL queries, and I need to do something about it.

I kept turning that statement over in my head. The managed GraphQL layer is firing too many SQL queries. What does that actually mean?

It means: queries are being issued, against a relational database, on behalf of an application this engineer is responsible for. And the engineer doesn't fully know how many, when, or with what transaction boundaries.

That last part is the one that matters. I asked them: if you're aggregating into yearly, monthly, and daily summary tables, and then setting a "processed" flag on the source records — and the very last UPDATE fails — can you roll all of that back? Is the whole sequence under your control?

I'm not sure they fully understood the question. To be fair, in the world they were handed on day one, the question doesn't naturally come up. The way the queries were resolved broke the unit of work into independent pieces, and each piece looked atomic on its own.

That isn't an SQL problem. It's a control problem.

A web design analogy

If I had to put this another way:

You can build a beautiful website using a no-code tool today. The output looks great. It deploys fine. It probably even works in production for a while.

But when something needs adjusting at the level of the generated code, you're stuck. The tool has handed you a polished surface, and not the means to repair it. For prototyping, this is excellent. For long-term operation, it's a problem you'll only discover the day you need to fix something the tool didn't anticipate.

Serverless plus heavy abstraction layers, given to an engineer on day one, is a similar situation — except the things they can't repair include cost, performance, and transactional integrity, all at once.

The application engineer is the right judge — they just need to be able to see

Here's the part that often gets reversed in these discussions.

The right person to judge whether an application is well-optimized is the application engineer who built it. They know the business requirements. They know which endpoint is hit by 1M requests a day, and which one is hit by 10. They know which tables grow linearly with users and which grow with the square of users. Infrastructure people, by their position, often don't have this context — not because they lack ability, but because the role doesn't naturally include the business reasoning behind every endpoint. They can't make this judgment from the outside.

The application engineer is the right judge.

But to judge, they need to be able to see. They need to know how many SQL queries their endpoint issues. They need to know what transactions they own. They need to know what happens when the third write succeeds and the fourth fails. None of this is obscure or fancy — it's the basic literacy of running a relational database under load.

The problem isn't that abstractions exist. Abstractions are fine. The problem is that abstractions are now the first thing an engineer encounters, and the things underneath them are made deliberately invisible.

My setup, for what it's worth

I run something called LDX hub. It's a public API platform on top of an internal hub I've been growing for years. Five services, document processing, the usual.

For the public-facing edge, I use a managed gateway on a flat-rate monthly subscription. It's "serverless" in shape, but the billing is fixed. There is no cost-spike risk to monitor for. If the bill could ever scale with traffic — even gracefully — I would seriously reconsider. The flat rate is the entire reason this part of the stack is comfortable to me.

For the compute layer, I run Java on EC2. Java's cold-start cost makes a long-running process the natural fit, but that's only half the reason. The other half is that EC2 has fixed limits. When something is wrong with the application, the fixed ceiling forces me to see it. I keep some old-fashioned things — server-side metrics, per-segment timing logs that record how long each part of a request took, alerts when something runs slower than it should — and these tell me, fairly directly, whether the application is doing its job efficiently or not.

For the database, I run my own RDB on EC2 too. Managed databases would handle backups and patches for me, but they would also schedule downtime I can't always control. I prefer the option of doing maintenance myself, on my schedule, with the techniques I've used for two decades — including running two databases in parallel through an application-layer two-phase commit, then cutting over, all without taking the system down. None of that works if the database is something I can't touch.

The whole stack is in AWS. None of it is "old school" in the sense of being on physical hardware. But each layer was chosen so that the things I should be able to see remain visible, and the things I should be able to control remain in my control.

This is not what you should do. This is what 24 years has taught one specific person to do.

Closing

I'm not against abstractions. I use them. The managed gateway in front of LDX hub is one. Cloud is one. Even my IDE is one.

What I'm against is starting there.

If you learn to write applications in an environment where you can't see what you're consuming, you don't learn the relationship between what you wrote and what your system did. You also don't learn how to cover the gap when something goes wrong. Twenty-four years from now, you'll still be guessing at it.

The engineers I see escape this trap usually do it because someone — often by accident — exposed them to a system where the lights were on.

I don't know if that's a fixable situation at the level of an industry. I work around it in my own setup by keeping the lights on — not because visibility is a virtue, but because the business logic is the one thing in my stack that no one else will get right for me. Everything else exists to give me time to get that part right.

Experience widens the set of choices that work for that. I'm not arguing against any of those choices. I'm arguing against the day one where there isn't a choice yet.

Built with Claude (Opus).

Earlier in this series:

Build a multi-step n8n Form with dynamic dropdowns (no plugin needed)

Hideki Mori — Wed, 03 Jun 2026 13:00:00 +0000

You want a multi-step form in n8n. Each step's dropdown depends on what the user picked or uploaded in the previous step. You search for "n8n dynamic dropdown" and find static fieldOptions examples and the occasional "use a Code node and hope."

I had the same problem building the distribution workflow for LDX hub, an AI document processing API. I wanted one workflow where a user picks one of five services, then walks through engine selection, file upload, and output format — with every dropdown computed from the previous step.

It turns out n8n already supports this. The feature is just hidden behind one toggle on the Form node.

This post walks through the pattern, with working code, three things to watch out for, and a link to a complete reference workflow you can import.

The one toggle that changes everything

The n8n Form node has a setting called Define Form. The default is Using Fields Below — you add fields in the UI like a typical form builder. There's a second option: Using JSON.

In JSON mode, the entire field array becomes an n8n expression. You return a JavaScript array where each element is a field definition, and you can reference any previous step's data inside that expression.

That's the whole technique. Everything below is just showing what you can do once you flip that switch.

Here's the chain we're going to build, for one branch of the workflow:

Form Trigger collects the API key and the service the user wants to use. The HTTP Request fetches the available engines from LDX hub. Then a sequence of Form / Set / Form / Set / Form steps progressively narrows the user's choices based on what came before. The LDX hub node runs the job. A final Form node displays the result.

The minimal example: dropdown from an API call

The simplest dynamic dropdown is: call an endpoint that returns a list, render that list as options.

LDX hub's /extractdoc/engines endpoint returns the available extraction engines without authentication. Calling it from n8n:

HTTP Request node
  URL: https://gw.ldxhub.io/extractdoc/engines

The actual response right now:

{
  "data": [
    {
      "id": "ki/extract",
      "display_name": "KI Extract",
      "provider": "ki",
      "description": "Extracts plain text from documents in reading order...",
      "supported_conversions": [
        { "from": "pdf",  "to": "text"  },
        { "from": "pdf",  "to": "jsonl" },
        { "from": "docx", "to": "text"  },
        { "from": "docx", "to": "jsonl" },
        { "from": "xlsx", "to": "text"  },
        { "from": "xlsx", "to": "jsonl" },
        { "from": "pptx", "to": "text"  },
        { "from": "pptx", "to": "jsonl" }
      ]
    }
  ]
}

One engine today. If the provider adds more tomorrow, they show up in the response automatically — and, as you're about to see, in the dropdown.

The Form node that follows the HTTP Request:

Form node
  Define Form: Using JSON
  JSON Output:
    {{ [
      {
        fieldLabel: "Engine",
        fieldName: "engine",
        fieldType: "dropdown",
        fieldOptions: {
          values: $json.data.map(e => ({ option: e.id }))
        },
        requiredField: true
      }
    ] }}

The expression returns an array with one field. The field is a dropdown. Its options are computed by mapping the HTTP response's data array into the shape n8n expects ({ option: "ki/extract" }).

When the form renders, the user sees ki/extract as the only choice. The list reflects whatever the API returned just now, not what you hardcoded last week. That's the whole future-proofing argument for doing it this way.

Going one level deeper: filter by user's choice

Static dropdowns are easy. The interesting case is when one dropdown's options depend on what the user chose in a previous dropdown.

After the user picks an engine, I want to compute which input file formats it supports. That information is in the engine's supported_conversions array. A Set node does the derivation:

Set node
  Assignments:
    name:  from_options
    type:  array
    value: {{ $('ExtractDoc: Get Engines').item.json.data
              .find(e => e.id === $json.engine)
              .supported_conversions
              .map(c => c.from)
              .filter((v, i, a) => a.indexOf(v) === i) }}

For ki/extract, this produces ["pdf", "docx", "xlsx", "pptx"].

Three things to notice in that expression:

$('ExtractDoc: Get Engines').item.json — the long form for cross-step reference. The short form $json only sees the immediately previous step's data. To reach back past the Form node that ran in between, you need the long form. This is the single biggest gotcha. More on this below.
$json.engine — the immediately previous step's data, which is the engine the user just selected.
.filter((v, i, a) => a.indexOf(v) === i) — uniquify. Engines advertise the same input format across multiple conversion pairs (pdf → text, pdf → jsonl), and you don't want the dropdown to repeat "pdf" four times.

The next Form node renders the file upload field, restricting accepted file types to what the chosen engine actually supports:

Form node
  Define Form: Using JSON
  JSON Output:
    {{ [
      {
        fieldLabel: "Source File",
        fieldName: "file",
        fieldType: "file",
        acceptFileTypes: "." + $json.from_options.join(",."),
        requiredField: true
      }
    ] }}

acceptFileTypes becomes the browser's <input accept="..."> attribute. With from_options = ["pdf", "docx", "xlsx", "pptx"], the resulting value is .pdf,.docx,.xlsx,.pptx — the user's file picker shows only those four types.

Even one more level: filter output by the uploaded file

The output format dropdown depends on what file the user actually uploaded — not what the engine generally supports, but what it can convert this specific input into.

This is where you reach into the uploaded file's metadata via $binary:

Set node
  Assignments:
    name:  to_options
    type:  array
    value: {{ (() => {
      const map = { jpg: 'jpeg', tif: 'tiff' };
      const raw = ($binary.file.fileExtension || '').toLowerCase();
      const from = map[raw] || raw;
      return $('ExtractDoc: Get Engines').item.json.data
        .find(e => e.id === $('ExtractDoc: Select Engine').item.json.engine)
        .supported_conversions
        .filter(c => c.from === from)
        .map(c => c.to)
        .filter((v, i, a) => a.indexOf(v) === i);
    })() }}

A few notes on this expression:

IIFE wrapper (() => { ... })() — to use local variables (map, raw, from) and an explicit return. n8n expressions are JavaScript; any valid JS works inside {{ }}.
Extension mapping — $binary.file.fileExtension returns whatever the user's file is named with. APIs sometimes use a canonical form (e.g., jpeg rather than jpg); a small map normalizes the boundary so the filter doesn't miss matches.
Two long-form references — $('ExtractDoc: Get Engines') for the engine list, $('ExtractDoc: Select Engine') for the user's selection. Long form everywhere.

For a user uploading a PDF against ki/extract, this resolves to ["text", "jsonl"]. The output dropdown is then trivial:

Form node
  Define Form: Using JSON
  JSON Output:
    {{ [
      {
        fieldLabel: "Output Format",
        fieldName: "output_format",
        fieldType: "dropdown",
        fieldOptions: {
          values: $json.to_options.map(t => ({ option: t }))
        },
        requiredField: true
      }
    ] }}

Here's what the user sees on the entry page of the rendered form, before any of the dynamic dropdowns appear:

Three things to watch out for

1. The short form `$json` does not reach across forms

$json refers to the immediately previous node's output. The moment a Form node sits between two nodes, $json can't see the data from before that Form.

Fix: the long form, $('Node Name').item.json.field. Works from anywhere in the workflow, regardless of how many nodes intervene.

Make it your default. Use the long form even when the short form would work — it'll save you when you later insert a Form node and don't want to rewrite three expressions.

2. Binary data needs an explicit pass-through

Form nodes return data on the json channel. The file the user uploaded sits on a separate binary channel that doesn't automatically propagate through Set nodes, Switch nodes, or subsequent Form nodes. To carry the binary forward to the node that actually consumes it, insert a Code node:

return $input.all().map(item => ({
  json: item.json,
  binary: $('ExtractDoc: Upload File').item.binary
}));

This is the smallest Code node that does anything useful. Steal it.

3. When exporting as a template, blank out the `webhookId` fields

The Form Trigger and Form nodes each carry a webhookId UUID in the exported JSON. n8n preserves these on import — it doesn't regenerate them — so your IDs travel with the workflow into the importer's instance.

This is a known sharp edge in n8n's import path (issue #18683). The convention for shareable templates is to strip the IDs before publishing: set every webhookId value to "". The importing instance allocates fresh ones on first save.

If you forget, the most common failure mode is silent webhook hijacking — calls intended for your original workflow get routed to the imported one, or vice versa.

The reference workflow below ships with every webhookId blanked.

Why this matters

The default n8n template is a one-configuration workflow. You build it for your exact use case, save it, and it works for you. Anyone else who imports it either matches your configuration exactly or edits the JSON by hand.

Dynamic dropdowns change that. The same workflow now adapts to the user — their file, their choice of engine, their available output formats. The template becomes a small application instead of a personal artifact.

For LDX hub, this meant one workflow could expose five different AI services with all their valid configurations, without me hardcoding any of them. When the provider adds a sixth engine tomorrow, the workflow doesn't change. The Get Engines call returns one more entry, the dropdown shows one more option, the rest of the flow handles it.

That's the reason this technique is worth knowing. Not because dynamic dropdowns are interesting in themselves, but because they're the part of the n8n stack that lets you ship a configurable workflow.

The complete reference workflow

The full demo — five services, every dropdown driven by this pattern, plus dynamic credentials (a separate post) — ships with the n8n-nodes-ldxhub npm package as examples/all-services-demo.json. Import it into your n8n instance and inspect any of the five service paths to see the pattern in production form.

If you want to run it against LDX hub, get a free API key at gw.portal.ldxhub.io — 25,000 credits per month, no card. If you just want the pattern, the JSON is permissively licensed and the dropdown logic is portable to any API.

Closing

The dropdown pattern collapses what looks like a hard problem ("how do I make my n8n template work for arbitrary users") into something almost boring ("call an endpoint, render its response as options"). Most of the configurability complexity I've fought over the years dissolves the same way, once I find the right boundary to draw.

The interesting part wasn't writing the expressions. It was discovering that the toggle had been sitting there in the Form node settings the whole time. The technique looks novel only because it's underdocumented.

If you've been building n8n templates that only work for your exact setup, try moving one configuration knob to a dropdown driven by an API call. That's where this starts paying off.

The loop I didn't notice closing

Hideki Mori — Mon, 01 Jun 2026 13:00:00 +0000

Seven weeks ago I started using AI for work. Two weeks after that, I published an article. Seven weeks after that — today — the article is one of sixteen, and they are all in a memory file that the AI reads at the start of every new conversation.

I didn't notice the loop until I named it.

This is a note about that loop, what it is, what it isn't, and why I keep publishing even though the loop doesn't strictly need me to.

The shape

It runs like this:

I decide what to do.
I work it out with the AI — usually in dialogue, sometimes by pasting raw code or data.
The dialogue becomes a record. Sometimes a memory entry. Sometimes a published article.
The record becomes context for the next conversation, which informs the next decision.

It didn't look this clean while it was happening. The numbering is hindsight. From inside, the steps overlap.

The first step is the one I keep. Direction is mine: what to build, what to write, what to negotiate. The history that shapes those decisions — twenty-four years of solo work, my company, my family, my health — is also mine. The AI is not setting direction.

The second step is where most of the leverage is. I describe what I want to do as completely as I can, sometimes by handing over source code. Then I ask: does this look right? Is there a path I'm missing? Where would this break? I'm opening drawers — possibilities I half-saw in my own head — and checking which ones open cleanly. When one opens cleanly, that is the GO signal. Not "will this succeed" but "this is doable, so do it."

The third step happens almost without effort. The conversation already exists as text. Some of it becomes a memory entry I add deliberately. Some of it becomes raw material for an article. The article writes itself partly because I have already explained the thing to the AI.

The fourth step is the one that took longest to arrive — and the one I want to be most careful about describing.

Three phases, not one

The loop didn't close in a moment. It accumulated.

In April, when I started using AI, it was just an easier way to write about things I already knew. My first published article was about a technique I had been using for years — a way of decomposing one long LLM prompt into two stages. I had named the technique privately. Explaining it to the AI turned the explanation into a draft. The article went out two weeks after I started. The AI didn't discover the technique; I had it already. The AI made it writable.

That was phase one. AI as a transcriber for things I already had.

A few weeks later, something shifted. The dialogue started shaping execution. When I redesigned the pricing model, the rate formula went through several iterations in conversation. When I built the chunked upload API, the chunk size and the format were chosen in the back-and-forth, not before. The decisions were still mine — I confirmed each one — but the candidate options came from the dialogue. I would not have arrived at exactly the same designs alone. Probably similar. Not the same.

That was phase two. AI as a tactical partner inside the execution.

The third phase took longer. It needed a critical mass of accumulated record. By the time I had a dozen published articles, a dense memory file, and weeks of transcripts, something else became possible: the AI could read across all of that in a single conversation. Now when I plan the next thing — which article to publish next, how to structure the next negotiation, whether to take a particular technical bet — I am not feeding context from scratch. The context is loaded. The conversation starts from where the last conversation left off, three weeks ago, with full continuity.

That was phase three. The accumulated record informing the next execution.

What it feels like

Two things stand out.

First, there is no shame and no time pressure. Explaining your full background to a human advisor is sometimes painful. You skip parts because they are embarrassing, or because you don't want to bore them, or because the context would take an hour to set up. The failures, the half-finished detours, the impulses you talked yourself out of — those usually get edited out. With an AI you don't edit them out. You hand over everything you have, including raw code, and ask what it sees. The friction of being honest is much lower.

Second, the bottleneck is mine. The AI doesn't tire. I do. When the loop slows down, it slows down because I am tired, distracted, or running into something I haven't thought through yet. The tool itself is patient in a way humans cannot be. This shifts the constraint structure of the work. The limit is my own attention, not someone else's calendar.

I open every drawer I might be able to pull out. Some open cleanly. Some don't. The cleanly-opening ones are the GO signal. Success or failure is not the test — the test is whether the thing looks doable from where I am standing. If it does, I go.

Tactical, not strategic

I want to be careful with the word "strategy."

The high-level direction is mine. The decisions about what to build, what to refuse, what to invest in, where my career goes — those come from my own history, my values, the people in my life, my health. The AI is not setting that direction.

The execution is collaborative. The drawer-opening is collaborative. The articulation is collaborative.

So when I describe the loop, I would call it a tactical loop, not a strategic one. The intent stays mine. The execution finds its shape in the dialogue.

This distinction matters because the situation is easy to misread. "Solo developer outsources thinking to AI" is wrong. "Solo developer uses AI as a tactical tool with persistent memory" is closer. The agency is intact.

The recursive part

This article is in the loop.

Earlier today I asked the AI what I should write about next. It read the memory and the recent transcripts and proposed this — the loop itself. We discussed it. I gave my felt-sense answers about what it is like from the inside. The conversation by then already contained most of the structure. The AI wrote a draft from it. I refined. The article will be published, become part of the memory, and inform the next decision about what to write.

The article describes the phenomenon it is also an instance of.

This is not theater. It is just what the loop looks like when it is also reflective.

Why publish, then

If the loop runs on memory and transcripts, what is the public article for?

If I am honest, the loop doesn't strictly need it. The closed loop runs fine on internal artifacts.

But two things hold.

First, writing for an audience tightens the thought differently than writing for an AI. The forcing function is different. The fear of being misread, of saying something stupid in public, of being quoted out of context — these tighten the prose in ways talking to an AI does not. I get a cleaner record by publishing than by just transcribing.

Second, and this is the one that matters more: not everyone can run this loop. I see colleagues with the same tools, the same access, the same time, and the gap is large. Some people have the sense for it, and others don't. The tool does not close that gap. If it could, the tool would already be replacing judgment — and it isn't.

This is the structural point. AI cannot teach humans to use AI well. If it could, AI would not need humans at all. The persistence of the skill gap is the same fact as the persistence of human judgment. The two cannot be separated.

So I publish. Not because the loop needs it. Because the sense — the thing that lets the loop run at all — isn't transferable through the tool. It transfers, if at all, by watching someone else use it.

Closing

I started seven weeks ago without intending to start a loop. The first article was a side effect of being asked to explain something. Then the dialogue started shaping the execution. Then the record started shaping what came next. The loop closed without my noticing.

When I named it, I could see it.

The next conversation has already started.

Built with Claude (Opus).

Earlier in this series:

72% -> 75% -> 92%: a reproducible RAG validation

Hideki Mori — Fri, 29 May 2026 13:00:00 +0000

I expected converting docs into Q&A pairs to improve retrieval. It mostly didn't.

I built three knowledge bases from the same source document and ran the same twelve questions against each, three times.

Raw markdown chunks: 72%
Q&A facts from a generic prompt: 75%
Q&A facts from a retrieval-aware prompt: 92%

The 75% caught me. Naive Q&A conversion lifts retrieval by three points — a wash, not a gain. The +20 over raw markdown comes from something else entirely: five prompt design rules applied at fact-generation time. The rules cluster around two ideas — each fact should answer fully on its own, and the tokens retrieval needs (service names, parameter names, identifiers) should survive verbatim from source to indexed fact.

This is a reproducible record of where the gains actually came from.

The full repo, including every prompt, every fact, every chatbot response: github.com/HidekiMori/rag-accordion-demo (MIT).

1. The setup

The source document was the LDX hub developer portal — an 821-line Markdown file describing five API services (StructFlow, RefineLoop, RenderOCR, CastDoc, and ExtractDoc). It mixes prose, parameter tables, JSON examples, and a cross-cutting "Errors" section. Long enough to test retrieval at scale, structured enough to test what each piece of the pipeline does.

From this document, three knowledge bases were built:

mdx_direct — the raw Markdown, chunked on \n\n, 1024 tokens per chunk, 50 token overlap.
naive_facts — Q&A facts produced from the document by a generic "extract Q&A pairs from this" prompt. 78 facts, one per JSONL line.
best_facts — Q&A facts produced by a Stage 2 prompt with five explicit rules. 82 facts.

All three are loaded into Dify Cloud as Knowledge Bases. Same embedding model (OpenAI text-embedding-3-large, default dimensions). Same retrieval (Hybrid Search, Weighted Score, 0.7 semantic / 0.3 keyword, Top K=3). Same chatbot LLM (OpenAI GPT-5.5). Same system prompt. The only variable across runs is which KB is attached.

Dify Cloud's vector storage runs on TiDB Cloud Starter — see PingCAP's case study on Dify's consolidation. I didn't write SQL against TiDB directly; what matters here is that Hybrid Search on top of TiDB is what made the keyword side of Rule 5 (below) visible in the results.

The Q&A facts were produced by a two-stage StructFlow pipeline. StructFlow is a generalized "input + instructions → structured output" function, not a structuring tool per se — the instructions decide what the output looks like, so the same function produces 53 self-contained sections in Stage 1 and Q&A facts in Stage 2. Both stages run on Google Gemini 3.5 Flash at temperature 0. Stage 1 outputs a sections array; Stage 2 outputs a facts array. Each array gets flattened into line-per-record JSONL between stages — the shape §5 below calls the "accordion." The Stage 1 prompt is identical for both naive_facts and best_facts — only the Stage 2 prompt differs.

A note on naming. StructFlow appears in this article in two roles: as a service documented in the test corpus (the LDX hub developer portal), and as the engine that built the Q&A facts from that corpus. Same tool, two contexts. When "StructFlow" shows up in the example facts and test questions, it is the service-in-corpus role; when it shows up in pipeline descriptions and the accordion diagram, it is the engine role.

Twelve test questions, each designed to probe a specific retrieval challenge (direct lookup, default value buried in a parameter list, cross-service comparison, hidden entity inside a code block, casual phrasing, cross-cutting concern scoped to a service, end-to-end workflow synthesis). Three independent runs per KB. Twelve questions × three KBs × three runs = 108 graded chatbot responses, scored as ✅ / ⚠️ / ❌.

Grading was manual, against a per-question rubric prepared before runs: ✅ for a complete answer that included every expected piece of information, ⚠️ for a partial or incomplete answer (e.g., missing the partial-failure warning in Q12), and ❌ for a wrong answer or a "not in the documentation" refusal when the answer was actually present in the source. Aggregate percentages treat ✅ as correct and both ⚠️ and ❌ as not correct — no partial credit. Per-question patterns and verbatim chatbot responses for all 108 runs are committed under results/ in the repo, so anyone can re-grade if they disagree with the rubric.

2. The headline numbers

KB	Accuracy	vs `mdx_direct`
`mdx_direct`	72%	— (baseline)
`naive_facts`	75%	+3 pt (operationally negligible)
`best_facts`	92%	+20 pt (and +17 over naive)

The +3 pt for naive Q&A conversion is a wash, not a gain. Looking question by question reveals why:

Question	`mdx_direct`	`naive_facts`	Instance change
Q2 (`max_revisions` default)	0/3	3/3	+3 (genuine fix)
Q6 (is LDX hub free?)	0/3	3/3	+3 (genuine fix)
Q4 (RenderOCR vs CastDoc)	3/3	0/3	−3 (genuine break)
Q12 (`completed` for StructFlow)	3/3	0/3	−3 (genuine break)
Q10 (scanned-contracts workflow)	2/3	3/3	+1 (mdx run variance)

The four genuine fix/break pairs cancel exactly at the instance level: +3 +3 −3 −3 = 0. The entire +3 pt difference (naive 27/36 vs mdx 26/36) comes from Q10 alone — where mdx_direct dropped to ⚠️ on a single run (the ExtractDoc→StructFlow chain collapsed that run) while naive_facts stayed ✅ across all three. That +1 instance is run variance on the raw-markdown side, not a retrieval gain from Q&A conversion. Naive Q&A shuffles where the failures land (Q2/Q6 fixed, Q4/Q12 broken) and nets out at zero; the headline +3 pt is noise on Q10.

best_facts keeps all four ✅, and brings six more questions from partial to full credit. Same Stage 1 sections, same LLM, same retrieval — only the Stage 2 prompt differs between naive_facts and best_facts.

The structural gap reproduced across all three runs of all three KBs without exception. It is not statistical noise.

That said, this is not a benchmark paper. It is a controlled engineering validation on one realistic corpus, with a deliberately small question battery designed to probe specific retrieval failure modes. Whether the five rules below hold under different document structures, retrieval backends, or chunking strategies is something the repo is designed to let you check on your own corpus — not something this single validation establishes.

3. The five rules

These are the rules encoded in the retrieval-aware Stage 2 prompt. Each one prevents a specific failure mode.

Rule 1 — Self-contained answers

Every fact must answer its question fully on its own, without needing to read other facts.

Hybrid Search returns the top three chunks. If the answer is split across multiple facts — "this is the default" + "the parameter is max_revisions" + "RefineLoop accepts these settings" — retrieval has to pull all three. That does not always happen. When each fact carries the full picture in one place, retrieval only needs to land on that one entry.

In practice: the best_facts entry for "what are the possible job statuses?" names every value (queued, processing, completed, failed) and what each means, in one fact.

Rule 2 — Developer-friendly question phrasing

Use the way real users would actually type the query: "How do I...?", "What is the default value of...?", "Which formats does X support?"

Embeddings reward semantic similarity. If the generated question is phrased like a real user query, the embedding lands close in vector space. Declarative summaries ("Describe the configuration of...") sit further away from how queries actually arrive at retrieval time.

This rule is easy to underestimate. It costs nothing at generation time and pays back on every retrieval.

A note on evidence: this validation does not isolate Rule 2's effect. Both naive_facts and best_facts already produce question-shaped questions, so the rule is not directly tested here. It is included because the failure mode (declarative summaries instead of questions) is common in prompts that ask for "summaries" or "key points," and once it occurs, retrieval degrades.

Rule 3 — Exact preservation of technical identifiers

API names, endpoint paths, parameter names, enum values, code snippets — keep them verbatim. Do not rephrase.

Hybrid Search has two channels: vector and keyword. The keyword channel is a literal-token match. max_revisions, results[].status, ki/ocr — these strings only contribute if they appear verbatim. Paraphrased ("the revision count parameter") loses the keyword channel entirely.

The vector channel can sometimes carry it. Often it cannot. The combined score drops below the cutoff and the fact never enters the top three.

Rule 4 — Service-specific facts for cross-cutting information

When a section describes errors, statuses, or behaviors tied to a specific service, generate a fact with the service name in both the question and the answer.

Source documents often place cross-cutting information in standalone sections away from the services they affect. Our source has a ## Errors section that includes:

StructFlow jobs may also have status: completed with some individual records marked failed — always check summary.failed_count and each results[].status to detect partial failures.

The section header is just "Errors", not "StructFlow errors". A generic Q&A extractor handles this content inconsistently. In our naive_facts run, the partial-failure content was skipped entirely — grep "partial failure" data/facts_naive.txt returns nothing.

The retrieval pipeline then cannot answer What does completed mean for a StructFlow job? because no indexed fact connects completed, StructFlow, and partial failures in the same line. This is Q12, and naive achieves zero correct answers across three runs.

The retrieval-aware version forces Stage 2 to generate a service-scoped variant: a fact whose question is How should I check for partial failures in a completed StructFlow job?, with answer text that mentions StructFlow explicitly and keeps every identifier verbatim. Q12 then resolves cleanly on every run.

Rule 5 — Deliberate keyword design

Each fact carries a keywords field with three to seven short tokens — service names, parameters, concepts. These tokens are direct ammunition for the keyword channel of Hybrid Search.

Without explicit guidance, the LLM tends toward loose, descriptive keywords. A naive fact about the wait parameter ends up with ["wait", "connection", "timeout", "polling"] — only wait is LDX hub-specific. The retrieval-aware version keeps ["StructFlow", "curl", "job_id", "wait"] — service name and resource type included.

This is the rule that resolves Q4 in the validation. The naive prompt did generate a RenderOCR primary-role fact, but its keywords were ["OCR", "scanned PDF", "Office files", "layout preservation", "languages"] — no literal RenderOCR token. When the user types "RenderOCR vs CastDoc?", the keyword channel contributes far less than it could, and the vector channel alone does not consistently lift this fact into the top three. The retrieval-aware version puts RenderOCR in every RenderOCR-scoped fact's keywords. The fact gets retrieved.

The full prompts, with examples and failure modes for each rule, are in prompt_engineering.md.

4. The one question that defeats every prompt

Q8 ("what engines are available for OCR?") is the only question that fails in all three KBs. The source mentions "KI OCR" once in a prose bullet at line 157 — Powered by KI OCR, a battle-tested enterprise OCR engine — and the engine ID ki/ocr lives inside the JSON response example of GET /renderocr/engines at line 644. Neither location surfaces consistently for the query. The prose bullet gets dominated by other RenderOCR feature points. The JSON code block is hard for both raw chunking and Q&A generation to digest.

Neither prompt rescued this. Q&A conversion in this run did not promote either form into a retrievable "OCR engine name" fact. The Stage 2 best prompt knows about identifier preservation (Rule 3), but it was not given explicit guidance to lift entities out of code blocks into prose-style facts.

This is the honest limit of what the five rules can do here. Missing data is missing data. Future work: explicit code-block entity extraction, or a follow-up Stage 2 pass that lifts JSON-embedded identifiers into their own facts.

5. The accordion pattern

The mechanism that produces one JSONL line per Q&A fact, from any structured source:

document
  → Stage 1 (segmenter): { sections: [...] }
  → flatten: one section per JSONL line
  → Stage 2 (extractor): { facts: [...] } per section
  → flatten: one fact per JSONL line

The same shape implemented in Dify. Stage 1 (S1) and Stage 2 (S2) StructFlow nodes both run on Google Gemini 3.5 Flash. Flatten nodes turn each stage's array output into line-per-record JSONL. Save nodes write the intermediate files for inspection. Full YAML: workflows/dify-accordion.yml in the repo.

The name "accordion" comes from the shape: 1 doc → N sections → M facts, with a flatten step after each stage to expand array outputs into line-per-record JSONL. Both stages are StructFlow jobs — the LDX hub structured-extraction service. The same mechanism works on HTML, PDF chapters, DOCX heading styles, or any text where a section boundary can be defined.

What this demo shows is that the mechanism itself is neutral. Paired with a generic Stage 2 prompt, the accordion produces facts that perform at roughly raw-chunking parity. The +17 pt over naive Q&A is not in the mechanism. It is in the Stage 2 prompt.

This is the part that surprised me most. I had expected the mechanism — the two-stage segment-then-extract design — to carry more of the weight. It does not. The Stage 2 prompt is the lever.

6. What this means in practice

A lot of RAG advice focuses on the retrieval side: which embedding model, which similarity function, which chunk size, how big the top-K window. Those decisions matter, but they all act on whatever facts have already been indexed. The shape of those facts — what each fact says, what tokens it carries, how it phrases its question — is decided at fact-generation time. And that decision is what this validation isolates.

Three takeaways for anyone building Q&A-style RAG over their own documents:

Do not assume Q&A conversion is automatically better than raw chunks. It can be, but only when the conversion preserves what retrieval actually needs. A generic "extract Q&A pairs" prompt is roughly neutral against well-chunked Markdown.
Keyword design carries the keyword-channel lift. Rule 5 above — putting service names in the keyword field is what fixed Q4. Identifier preservation (Rule 3) targets the same channel and becomes load-bearing when the model paraphrases, but at temperature 0 here the model preserved identifiers on its own, so it was insurance rather than the driver. Both cost nothing at generation time and are easy to encode in the Stage 2 prompt.
Cross-cutting sections need to be re-anchored to their services. Rule 4. A ## Errors section that mentions four products should produce four product-scoped facts, not one neutral fact. Otherwise no indexed fact connects the service name and the error in the same line, and retrieval cannot bridge the gap at query time.

These rules generalize to any domain with characteristic identifiers — drug names, statute codes, model numbers, CSS class libraries. The retrieval system already knows how to match strings. The prompt's job at generation time is to make sure the strings stay strings.

7. Open question — the prompt is the next bottleneck

The five rules describe what works. They do not describe how to apply them.

The Stage 2 best prompt used in this validation is heavily LDX hub-specific. It encodes that max_revisions is a parameter, that RenderOCR and CastDoc are distinct services, that ## Errors is a cross-cutting section, that StructFlow jobs can have completed status with failed records inside. Every one of those decisions was hand-written into the prompt by someone who already understood the domain.

This is fine for one domain. It does not generalize.

A team adopting this pattern for, say, drug labeling, statute codes, or CSS class libraries would have to write their own version of the Stage 2 prompt — with their own service names, their own cross-cutting concerns, their own identifiers to preserve. The know-how is not in the LLM. It is in the prompt author's head.

There are two paths out, and I have not yet validated which is correct.

The first is to codify the methodology. Build a checklist (the repo already has one in prompt_engineering.md) and trust that engineers using the pattern will fill it in for their domain. This is the documentation-as-scaffolding approach. It works for teams with strong technical writers. It does less for teams without them.

The second is to make the prompt itself a StructFlow output. Add a Stage 0 that ingests the source document and produces the Stage 2 prompt for that domain. The accordion stretches one more time: 1 doc → 1 prompt (Stage 0) → N sections (Stage 1) → M facts (Stage 2). The Stage 0 prompt would be the only domain-agnostic prompt in the system, and it would be reusable across any source.

I lean toward Stage 0 being a real possibility, but this part is still hypothetical — I have not validated it. The accordion mechanism already proves that one StructFlow step can turn one input into many structured outputs. There is no reason in principle why "the prompt for the next StructFlow step" cannot be one of those outputs. Whether that actually beats a hand-written domain prompt for retrieval quality is an open question. That is the next thing I want to test.

8. Closing

The repo is MIT-licensed and the Dify Workflow YAML is included — import it into Dify, drop in your own document, and rerun. The shortest possible summary of this whole note is to diff the two Stage 2 prompts: stage2_best.md vs stage2_naive.md. Everything else in this article unpacks what that diff is doing.

TiDB Cloud, accessed through Dify's Knowledge feature, is the silent infrastructure that made this validation reproducible without standing up a vector database from scratch.

Built with Claude (Opus).

Live report: at this speed, you don't theorize. You eliminate.

Hideki Mori — Mon, 25 May 2026 13:00:00 +0000

From April 15 to April 30. Two weeks. Solo. Plus an AI.

This is a live report — not a retrospective.

The earlier posts in this series have been about shape: the contract, the pattern, the twenty-four years of building alone. This one is about what happens when an AI is added to that shape and the speed changes.

I'm writing this while still inside it. The shape held. The speed didn't.

What I built

Two weeks. One person. Here's the list, flat and unromantic:

API gateway: Zuplo, five services unified behind one public API
Custom domains: gw.ldxhub.io for production, gw.portal.ldxhub.io for the developer portal
DevPortal: API reference auto-generated, plus introduction, per-service guides, pricing, MCP setup, "use anywhere"
Auth: Auth0 with Google OAuth, GitHub OAuth, and email — sign-up to first call in roughly thirty seconds
Free tier: 25,000 credits per month, no credit card required
Billing: a unified credit system, $0.0001 per credit, four plans (Free, Starter $15, Standard $50, Pro $150), overage billed at the same rate
Stripe integration: connected for paid plan subscriptions and overage settlement
Async metering pipeline: a separate path that fires credit consumption after a job finishes (minutes or longer after 202 Accepted), batched to the gateway's billing API
Five services published: StructFlow, RefineLoop, RenderOCR, CastDoc, ExtractDoc
Four channels integrated: n8n nodes (verified, on the marketplace), Dify plugin (verified, multilingual), MCP for AI assistants like Claude Desktop, plus the direct API
Marketing pages: four product pages on the corporate LP (ldxlab.io/ldxhub, plus per-service pages), each linking to the developer portal
Eight scheduled articles on dev.to and Zenn, covering the design philosophy. This one is article five.

That's the surface. None of it is glamorous. All of it had to be done.

The shape held

The shape from the earlier posts didn't change.

Jobs go in. The API holds the work. The API retries through whatever needs retrying. The API reports when there's a real result to report. The same shape that ran the music platform in 2003 and the e-book platform from 2006 to 2014, now wrapping a structured-extraction service and four others.

What changed was the speed within it.

What sped up, what didn't

Sped up:

API design iteration — every interface lived through three or four shapes before settling
Documentation in four languages (English, Japanese, Chinese, Portuguese) — because the marketplace plugins required it and there was no time to do it sequentially
Edge-case verbalization — "what happens if the input is missing both inputs and file_id?" — answered in writing the same hour the question came up
Marketplace plugin onboarding (n8n, Dify) — submission, review, version bumps
Migrations, fixtures, sanity checks

Didn't change:

Decisions about the billing structure
Where to draw the integration boundary (which engines, which surfaces)
What to ship and what to skip
What stays in the legacy internal API and what becomes a public service

The AI didn't replace judgment. It replaced most of the typing.

(Most. The wrappers that bridge the public services to the legacy internal API — those I typed myself. They were small, they were boring, and they were exactly the shape I had in my head from twenty-four years of doing this. Faster to type than to explain.)

What was hardest

The piece I almost gave up on was the credit metering for async jobs.

Most API gateways meter on the request — easy. What I needed was: meter when the job finishes, which is minutes (or much longer) after the request returns 202 Accepted.

I evaluated two gateways. Both could do async reporting on paper. The first one I took all the way through — the API was there, the docs were there, but the UI and the operational behavior had a rough edge to it that I couldn't quite ignore. I wanted the second one. So I went back.

The second gateway was where I wanted to land. But when I got there, I wasn't sure whether the async metering I needed was actually possible. The documentation was thin in exactly that spot. I tried their support bot. The bot didn't know either. Then a human came on, and the human walked me through how to fire metering events from the job-completion side, batched.

It worked.

That's the only piece of this build where I didn't know whether it was possible until someone on the other side confirmed it was. I want to remember that. Twenty-four years of building alone, and the fastest path through this particular unknown wasn't to figure it out alone — it was to ask, and to have the other side answer well.

(There was also a smaller stumble with Stripe. I assumed I'd need to configure something on the Stripe side to make the gateway's billing flow work. I spent a while looking for that something. There wasn't one. The gateway handled it end-to-end and Stripe just received what it received. Sometimes the answer to "how do I integrate this?" is "you already did.")

The decision volume

This is the part that surprised me.

The output increased dramatically. I expected that. What I didn't expect: the volume of decisions and branches multiplied with it. Each one had to be closed individually — there's no way around that. Closing each decision was also faster, so none of them became the bottleneck.

But the fatigue is different.

I've been building things alone for twenty-four years. I know what tired feels like. This is something else. The speed compresses everything — the questions, the answers, the small course corrections — into a window where nothing has time to settle. You're never in a phase. You're always at the seam.

Here's something I didn't expect from twenty-four years of solo work: I never used to worry about missing a branch. The volume of decisions was always within what one head could hold. Now, with the output multiplied, there's a new fear — that something I should have considered slipped past while I was closing five other things. The path keeps moving and the adjacent branches keep widening, and I want to see them all before I commit. That fear didn't exist before. It's not crippling. It's just present.

I don't have a clean answer for what to do about that. I'm reporting it because it seems important and it isn't in the AI-tooling articles I've read.

Elimination, not theory

Here's the part I want to keep.

At this speed, you don't theorize. You eliminate.

There isn't time to model out every option, weigh tradeoffs in a meeting, or build a deck. You hold a thing in your hand for an hour, see whether it survives contact with the next thing, and either keep it or remove it. What survives is what you didn't have time to argue with.

This isn't a productivity claim. It's a description.

When the friction is low enough — when typing is no longer the rate-limiter — the way decisions get made shifts. They get made by elimination, by what a thing fails to support, rather than by what a thing might enable. The negative case becomes louder than the positive case. You stop asking "what if we add this?" and start asking "what does this make it harder to remove later?"

I don't know if this generalizes. I know it's what happened in these two weeks.

Closing

Speed isn't a virtue. It's just what happens when the friction is gone. After twenty-four years, the friction I had left was mostly typing.

I removed the typing. The shape was already there.

The fatigue is part of the report.

Built with Claude (Opus).

Resources

LDX hub developer portal: gw.portal.ldxhub.io
n8n integration: n8n-nodes-ldxhub on npm
Dify plugin: LDX hub on Dify Marketplace
MCP endpoint: gw.ldxhub.io/mcp

Earlier in this series:

Dynamic isn't enough. Operations is the other half.

Hideki Mori — Mon, 18 May 2026 13:00:00 +0000

If you've been writing software for a few years, you eventually start designing for change.

A content delivery system: a new format will appear, a new player will appear, so let's not hard-code formats. An e-commerce site: a new payment method will be requested, so let's not hard-code billing logic. A document pipeline: a new processing engine will appear, so let's not hard-code engines.

This is good instinct. You read books like Analysis Patterns, you internalize the idea that the model should be flexible, you push concrete decisions out of code and into data. New format? Insert a row. New payment? Insert a row. New engine? Insert a row.

It's a beautiful pattern. It really does extend the lifespan of a system.

But after enough years of running systems built this way, here's the part that doesn't show up in the books:

Dynamic isn't enough. Operations is the other half — and that other half is usually paid by someone else.

The "wait, maybe..." moment

Reality always overshoots the model. Always.

You build a content system that handles formats dynamically, and then someone asks for a format whose delivery rules don't fit the existing shape. You build a payment system that takes new methods through configuration, and then someone wants a billing model where the "amount" isn't even computed at the same time as the "charge." You build an engine registry, and then a new engine doesn't conform to the lifecycle every other engine has assumed.

Each time, the moment looks the same. You stare at the request, and your first thought is: that's outside the model. And your second thought, a few minutes later, is:

Wait, maybe... if I interpret this field a little differently, and if I add one column here, and if I let this branch handle a special case... it fits. Sort of. It doesn't break anything.

So you do that.

The system keeps running. No downtime. No coordinated migration. No painful conversation with the integration partners. From your seat as the designer, the dynamic structure absorbed the change. The pattern worked.

That's the part designers love. That's the part that gets written about.

Who pays for the other half

Here's what's harder to see from the designer's seat: every "wait, maybe..." moment leaves a small residue somewhere in operations.

The operator now has to remember that for this particular case, the workflow is slightly different. The reporting tool needs a footnote. The on-call playbook gets one more conditional. The next person to onboard needs another paragraph of context. The integrating system has to send a value in a slightly unexpected place.

None of these are catastrophic. None of them break the system. Each one, on its own, is a small inconvenience.

But the small inconveniences accumulate. And the people accumulating them are usually not the people who designed the dynamic structure in the first place.

The designer experiences each "wait, maybe..." as a successful absorption. The operator experiences it as one more thing to remember. Same event, two ledgers. Only the designer's ledger gets reviewed.

This is where engineering satisfaction can become quietly self-serving. The system didn't break. The pattern held. Therefore the design is good — except good for whom, exactly?

The road I didn't take

There is, of course, an alternative. You can stop the system, ship version 2, ask everyone to migrate, and start clean.

A scheduled 24-hour outage. A v2 documentation packet sent to every integrating partner. A coordination meeting. A cutover.

I have, for twenty-four years, mostly chosen not to do this. I have preferred quiet absorption — interpretation, gentle reshaping, "wait, maybe..." — over coordinated rebuild.

Whether that was right, I genuinely don't know. There were probably operators along the way who would have been happier with one painful migration than with years of small accommodations. There were probably integrating systems whose engineers would have preferred a clean v2 over a v1 that kept quietly bending.

I chose to keep the shape. That choice has a cost. The cost is paid in operator-hours, in playbook footnotes, in the small extra cognitive load of working with a system that has absorbed more than its original model anticipated.

I'm not saying I was wrong. I'm saying: I'm still not sure.

Generic underneath, specific on top

There's one thing I do believe, with more confidence than the rest:

When the model gets very generic, the UI usually has to get very specific to compensate.

A maximally flexible data model — the kind that absorbs new formats, new payment methods, new engines — is, almost by definition, awkward to interact with directly. Direct interaction with a generic model means the human has to supply all the missing context. That's exhausting.

The good outcome is: the model stays generic underneath, and the UI is built specific to each use case on top. Each surface is custom. Each surface is rigid in exactly the way that makes it usable.

This is a hard decision to make, because every specific UI you build feels temporary. You're going to throw it away when the use case shifts. You build it knowing it has a shorter half-life than the model below it. That asymmetry is uncomfortable.

But I think the discomfort is the right discomfort. A long-lived generic core, with shorter-lived specific surfaces on top, is — based on what I've watched survive over twenty-four years — closer to how systems actually age well.

Three observations

None of these are conclusions:

Dynamic structure extends a system's life. It does not, on its own, make operating that system pleasant.
Every "wait, maybe..." absorption is a real engineering achievement and a small tax on someone downstream. Both of these are true.
If you make the model very generic, give the operators a UI that isn't generic.

Dynamic isn't enough. Operations is the other half — and that other half is usually paid by someone else.

After twenty-four years of this, that's the only thing I feel sure of.

Earlier in this series:

The Accordion Pattern: Why I stopped writing one fat LLM prompt
Nobody knows when a job will finish. I'd still like to report it accurately.
What survives when you build alone for 24 years.

DEV Community: Hideki Mori

The 3-line discipline

Three principles

Why three lines

Components: write the caller, run, write again, run

Even then, live data still surprises you

Twenty-four years of this

Billing asynchronous work exactly once

Three ways metering goes wrong

The mechanism: a durable outbox

Exactly once = at-least-once × at-most-once

Bill on success, and survive retries

The shape

Write the code well once, the spec stops bothering you

The hundred storefronts and the one carrier spec

What I didn't do: pre-generate

What I did: deterministic generation at request time

The mtime had to be fixed

Fifteen years of nobody touching it

What I was actually choosing

Twenty-four years of the same choice

Two patterns, five services, one n8n workflow

The shape

The spine: routing by static comparison

Two patterns inside

Pattern A: single-step form (StructFlow, RefineLoop — 7 nodes)

Pattern B: cascading multi-step form (RenderOCR, CastDoc, ExtractDoc — 10 nodes)

Why two patterns, not one

Anatomy of one path

The convergence: five paths, one node

The if/else pair: error endings

What consolidation looks like

Closing

Twenty four years, ten DB migrations, zero downtime

The seven minutes

The contract no one made me write

The shape

The thing nobody talks about: mixed states

Rollback was never a special case

Twenty four years later

Let your n8n template ask for the user's API key

The form asks, the credential listens

Wiring the credential to expression mode

Using the credential in an HTTP node

Alternative: skip the credential entirely

Three things to watch out for

1. The display-only error has different wording per credential type

2. The Password element type controls masking, not security

3. Credentials are global, expressions are runtime-scoped

When a custom node also supports expression credentials

Why this matters

The complete reference workflow

Closing

Abstractions are fine. Starting on them isn't.

Pain used to teach you when something was wrong

Serverless took three pains away

Pain 1: cost spikes that show up too late

Pain 2: performance degradation that auto-scaling hides

Pain 3: where the work actually happens

A web design analogy

The application engineer is the right judge — they just need to be able to see

My setup, for what it's worth

Closing

Build a multi-step n8n Form with dynamic dropdowns (no plugin needed)

The one toggle that changes everything

The minimal example: dropdown from an API call

Going one level deeper: filter by user's choice

Even one more level: filter output by the uploaded file

Three things to watch out for

1. The short form $json does not reach across forms

2. Binary data needs an explicit pass-through

3. When exporting as a template, blank out the webhookId fields

Why this matters

The complete reference workflow

Closing

The loop I didn't notice closing

The shape

Three phases, not one

What it feels like

Tactical, not strategic

2. The `Password` element type controls masking, not security

1. The short form `$json` does not reach across forms

3. When exporting as a template, blank out the `webhookId` fields