Microkernel and plug-in architectures

Definition and origin

A microkernel architecture, also called a plug-in architecture, splits an application into two kinds of part: a core system that contains the minimal, general functionality needed to run, and plug-ins that add or change behaviour without the core being modified. Plug-ins connect to the core only through published contracts, and the core finds them through a registry. Mark Richards and Neal Ford catalogue it as one of the classic architecture styles in Fundamentals of Software Architecture, and it fits the description of an architectural style given in Section 5.1: a named set of constraints on the elements (core, plug-ins) and connectors (contracts) of a system.

The idea grew up in product software: tools that are installed by many customers, each of whom wants something slightly different. Rather than maintain a separate version for each customer, the vendor ships one core and lets customers, partners or the vendor's own teams add plug-ins. Integrated development environments, web browsers, graphics editors and accounting packages all work this way. The name is borrowed from operating systems, where a microkernel is a very small kernel with everything else running outside it; the two ideas are related but should not be confused, as explained below.

A microkernel application is normally a single deployment unit, so it belongs with the monolithic styles of this chapter: one deployment unit, one process, one set of operational concerns. Plug-ins may be installed separately, but at run time they live inside, or right next to, the core.

How it works: core, plug-ins, registry and contracts

The core system contains what every installation needs: the main workflow, shared services such as logging or configuration, and the extension points where plug-ins attach. Richards and Ford describe it as the happy path through the application with little or no custom processing; in a food-delivery checkout, that is pricing a basket, taking payment and confirming the order. A good core is deliberately boring. Every special case that varies by customer, country or product line is a candidate to move out of it.

Plug-ins are independent, self-contained modules that contain specialised processing. They should depend only on the contract, not on each other and not on the core's internal classes. When one plug-in needs something another provides, the need should be met by the core (as a service it exposes through the contract) or the two plug-ins should be merged; plug-in-to-plug-in dependencies quietly turn a clean star into a tangle.

The registry records which plug-ins are available, what each is called, which version it is, which contract it implements and how to reach it. It can be as simple as a dictionary filled at start-up, a directory the core scans for manifests, entries in a package's metadata (as with Python entry points), a database table, or a remote service that lists plug-ins deployed elsewhere. The registry is what lets the core say "give me the tax rules for Germany" without knowing that a class called GermanTax exists.

Contracts define what a plug-in must provide and what it may rely on: an interface with method signatures, the data structures that cross it, the error behaviour and a version. In Eclipse a contract is an extension point declared in a plug-in manifest with a schema; in Visual Studio Code it is the extension API plus the contribution points listed in an extension's package.json; in your own code it is usually an interface (or a Python Protocol) in a small package of its own. Where the plug-in comes from another organisation and cannot follow your contract, an adapter translates between the two, exactly as in hexagonal architecture.

Plug-ins can be connected in three ways. Point-to-point, in-process calls are the norm: the core calls a method on the plug-in object. Separate-process plug-ins run in their own process and talk to the core through inter-process messages, which protects the core from crashes. Remote plug-ins sit behind an HTTP or messaging interface; this allows plug-ins in other languages or owned by other teams, but it adds network latency and failure modes, and the system starts to look like the distributed styles of Chapter 6.

Real examples

Eclipse. The Eclipse IDE is the textbook case. Its core is little more than a workbench and a plug-in runtime (built on Equinox, an implementation of the OSGi framework specification). Almost everything a developer sees, from the Java tooling to version-control integration, is a plug-in. Each plug-in has a manifest that declares what it needs, which extension points it offers to others, and which extensions it plugs into. Plug-ins are activated lazily, only when something actually needs them, so that hundreds of installed plug-ins do not slow start-up.

Visual Studio Code. Extensions declare activation events (open a Markdown file, run a command) so they load only when needed, and contribute commands, languages, themes and views through their manifest. Extensions run in a separate extension host process, so a misbehaving extension cannot freeze the editor's user interface. This is a good example of choosing process isolation for a plug-in ecosystem that includes thousands of third-party authors.

Web browsers. Browser extensions use a standard set of extension APIs and must declare the permissions they need (which sites they may read, whether they may see tabs or downloads) in a manifest. The browser enforces those permissions, because extension authors cannot be trusted by default.

Business rules engines. An insurer's claims system may keep the claims workflow in the core and put each jurisdiction's rules (what is covered, which documents are needed, statutory deadlines) in plug-ins. Tax engines, payroll systems and e-commerce platforms with payment-method plug-ins follow the same pattern: a stable process, with rules or providers that vary by country, product or customer.

Developer tools. The pytest test framework is built around the pluggy plug-in library; many of its own features are implemented as plug-ins using the same hooks that third parties use. Build tools, linters and static-site generators commonly do the same.

Plug-in isolation, versioning and compatibility

Three questions decide whether a plug-in architecture stays healthy over years: how isolated plug-ins are, how the contract evolves, and how incompatibility is detected.

Isolation. In-process plug-ins share the core's memory, threads and permissions. That is fast and simple, but one plug-in with an infinite loop, a memory leak or a security hole affects everything. The options, in increasing order of isolation and cost, are: in-process with defensive calls (timeouts, catching exceptions per plug-in, resource limits); a separate process or worker per plug-in or group of plug-ins; a sandbox such as a WebAssembly runtime or a restricted interpreter, which limits what plug-in code can touch; and a remote service. Choose by asking who writes the plug-ins. Your own team's tax rules can run in-process; arbitrary code from a public marketplace should not.

Versioning. The contract is an API, and the rules of Section 0.6 about breaking changes apply. Version the contract separately from the core, usually with semantic versioning: a new major version for breaking changes, a minor version for backward-compatible additions. Let each plug-in declare which contract version it was built for, and let the core declare which versions it supports. Additive change (new optional fields, new optional hooks) keeps old plug-ins working; when a breaking change is unavoidable, support the old and new major versions side by side for a published deprecation period.

Compatibility checks. Check compatibility when plug-ins are loaded, not when a customer first triggers them. A registry that refuses an incompatible plug-in at start-up, with a clear log message, turns a run-time bug into a deployment failure. Hyrum Wright's observation, known as Hyrum's law, is worth remembering here: with enough users, every observable behaviour of an interface will be depended on by someone, whatever the documentation says. Keep the contract small, keep core internals out of reach (Eclipse marks non-API packages as internal for this reason), and treat anything visible to plug-ins as part of the contract.

When to use it, and when not

Good fits. Product software that many customers install and customise. Systems with a stable workflow but many variants of one step: tax and payroll by country, insurance rules by jurisdiction, payment methods, file-format importers, shipping carriers. Platforms that want a third-party ecosystem. Systems where a regulator or customer changes rules often and you want those changes to be small, separately tested releases. The style also works inside a larger system: one service in a distributed architecture can itself be a microkernel.

Poor fits. Systems where you do not yet know what varies. Extension points designed in advance for imagined needs are speculative generality: they add machinery, slow the team down and are usually in the wrong place when the real need arrives (see the discussion of reversibility in Section 1.6). Systems that need very high scalability or fault isolation, since the whole thing scales and fails as one unit. Systems where plug-ins would need to coordinate closely with each other, which defeats the style's main benefit.

A practical rule: wait until you have built the same kind of variation two or three times, then extract the contract from the real cases. A contract derived from three working tax implementations will be far better than one guessed before the first.

# package: tax_contract  (version 2.1.0)
from dataclasses import dataclass
from decimal import Decimal
from typing import Protocol

CONTRACT_VERSION = (2, 1)

@dataclass(frozen=True)
class TaxLine:
    sku: str
    category: str      # "hot-food", "cold-food", "alcohol", "delivery-fee"
    net: Decimal       # never float for money

@dataclass(frozen=True)
class TaxResult:
    total_tax: Decimal
    breakdown: dict[str, Decimal]   # label shown on the receipt

class TaxRules(Protocol):
    country: str                    # ISO 3166-1 alpha-2, e.g. "DE"
    requires_contract: tuple[int, int]
    def calculate(self, lines: list[TaxLine], region: str | None) -> TaxResult: ...

from importlib.metadata import entry_points
from tax_contract import CONTRACT_VERSION

class UnsupportedCountry(Exception): pass

class TaxRegistry:
    def __init__(self, log):
        self._by_country = {}
        for ep in entry_points(group="fooddelivery.tax_rules"):
            plugin = ep.load()()
            major, minor = plugin.requires_contract
            if major != CONTRACT_VERSION[0] or minor > CONTRACT_VERSION[1]:
                log.warning("skipping %s: needs contract %s", ep.name, plugin.requires_contract)
                continue
            self._by_country[plugin.country] = plugin

    def for_country(self, country):
        if country not in self._by_country:
            raise UnsupportedCountry(country)   # fail loudly, never guess a rate
        return self._by_country[country]

Enforcing the style in code

A plug-in architecture only stays one if its rules are checked automatically. The structure that works in most languages has three kinds of package: a small contract package with interfaces and data types only; the core, which depends on the contract; and one package per plug-in, each depending on the contract and nothing else of yours.

Then enforce the dependency rules with tooling of the kind covered in Section 3.4: in Python, import-linter can forbid the core from importing any plug-in package and forbid plug-ins from importing each other or the core; in Java, ArchUnit tests or module systems (JPMS, OSGi) can do the same. Fail the build when a rule is broken.

Add a contract test suite: a set of tests written once against the contract and run against every plug-in in that plug-in's own pipeline. It checks behaviour the contract promises (rounding, empty input, error types), not each country's tax law, which the plug-in's own tests cover. Finally, add a start-up check or a deployment smoke test that loads every installed plug-in and verifies its contract version, so that incompatibilities are caught before users find them.