A format only one bank uses
A credit union asked the makers of a budgeting app for something ordinary: its members want to import their statements. The credit union's online banking exports them in its own fixed-width text format, one transaction per 80-character line, with the amount in columns 41 to 52.
The app already imports two formats: CSV files exported by banks, in a dozen column layouts, and OFX, a format many banks offer for personal finance software. Both live in one importStatement function that switches on the file type and shares date helpers. The last time a CSV layout was added, a change to those helpers swapped day and month in day-first dates for a week. The credit union means editing that function again and shipping the whole app, for one customer's members.
Reading fixed-width text is easy. Adding the third format, and the tenth, without touching code every other format depends on is not.
What every import does, whatever the file
Take the format out of an import and most of it stays the same. The app receives a file, works out which format it is, turns it into transactions, drops the ones already imported, shows the user a preview, and writes the confirmed ones to the account's ledger. Only two parts depend on the format: recognising the file and turning its bytes into transactions.
The Microkernel (or plug-in) architecture is built on that split. A minimal core keeps what does not vary: the workflow, registration and the shared contracts. Each variable part becomes a plug-in, a separate unit the core discovers and calls through an extension point, a contract the core publishes and promises to keep. Code editors and browsers grow this way: the core stays stable while extensions ship on their own schedule.
Here the extension point is a StatementImporter contract with three parts: a name, a canRead check that looks at the file name and its first bytes, and read, which takes the file and returns transactions in one shape the core defines. Each transaction has a date, an amount in the currency's minor units (cents, for dollars), a currency, a description, and the bank's own transaction id when the format carries one. CSV, OFX and the credit union's format become three importers that implement it.
Each importer implements the contract and also registers itself at start-up. The core asks the registry which importer reads a file, then calls it through the contract, never by name.
The extension point is a port in the sense of Hexagonal (Ports & Adapters); in this design several importers sit behind it at once, and the core picks one for each file. The importers are not the business parts of the app, such as budgets and accounts, which are always present and fixed when the app is built; dividing those is Modular Monolith. Importers are optional: one installation needs only CSV, another adds the credit union.
Finding importers the core has never heard of
The core never names an importer in its code; if it did, adding one would change the core again. A registry holds the importers that are present instead. At start-up the core loads plug-ins from a list it does not have compiled in: a folder it scans, a configuration file, or the platform's own mechanism, such as Java's ServiceLoader or Python's package entry points. Each plug-in it loads registers with its name and the contract version it was built for. This registry is a list in memory, not a Service Registry of network instances.
When a file arrives, the core asks the registry which importers claim it: none means an unsupported format, and two, say the generic CSV importer and one written for a single bank's CSV, need a rule set in advance, such as a priority per importer.
Where the core ends
The first version put duplicate detection inside each importer, since each knew its format best. The OFX importer matched on the bank's transaction id, the CSV importer on date, amount and description, and the credit union's importer, written in a hurry, did not check at all. Users importing an overlapping month got duplicates for one bank and not for another, and fixing that meant three changes in three plug-ins.
The rule that came out of it: what every import must obey lives in the core, and a plug-in knows only its format. Duplicate detection, the transaction shape and writing to the ledger belong to the core; knowing that the amount sits in columns 41 to 52 belongs to a plug-in. The opposite drift is as common: a core that collects if format is OFX special cases stops being minimal. Such a case usually means the contract lacks something, here an optional bank transaction id, which the core's duplicate check uses when present.
The contract every importer depends on
Every importer depends on the contract, so it is the one thing in the design that cannot change casually. Two changes show the difference:
- Adding an optional field, such as a
pendingflag for transactions the bank has not yet settled, keeps existing importers working, as long as the way the contract is represented lets existing importers omit it without a change or a rebuild, and the core treats a missing value as a default, here not pending. - Making
readhand back transactions one at a time instead of returning a list, so large files fit in memory, breaks every importer at once, including the credit union's, which the app's team does not maintain.
So the contract carries a version number, and each plug-in declares the version it was built against. When the core moves to version 2 it can keep accepting version 1 importers for a deprecation period, adapting their output, and the registry refuses an importer that needs a version the core does not support, with a message that names it, instead of loading it and failing in the middle of someone's import.
A version number only protects plug-ins that use nothing but the contract. The credit union's importer needed the account's currency and read it straight from the core's accounts table, so when the core renamed that column, the importer broke in a release that changed nothing in the contract. Once one plug-in depends on the core's internals, the core can no longer change those internals without breaking that plug-in. The fix was to pass the account's currency into read as part of the contract.
One malformed file, one stalled app
The credit union's importer runs inside the app's process, with its memory, its CPU time and its permissions, and a statement cut off in the middle of a line sent its parser into a loop that slowed the whole application, not just that import. The core can catch an error an importer throws and report that one file could not be read, but catching errors does nothing for a loop or a two-gigabyte allocation. Containing those takes a boundary around the plug-in, a separate process or a sandbox, and in either case CPU and memory limits and a supervisor that can stop a stuck import; calls across that boundary are no longer plain function calls. Sandboxing untrusted code: isolation, limits & egress covers the options, which matter most for code someone else wrote, like the credit union's.
The import core in the Challenge
The Microkernel / Plugin Challenge asks for a minimal core with only the essential workflow, explicit extension-point interfaces, plug-ins implementing them independently, a registry through which the core discovers them, and a design where adding or removing a plug-in never changes the core. Build the import feature with its three importers, each wired to the contract and the registry, and the core wired only to those two. Then delete the credit union's importer. If an edge from the core disappeared with it, the core knew that importer by name, and the design misses the requirement the Challenge is testing.