Skip to content
ArchXS

Practice

Building systems, and handing them over

I build production systems, backend, web and mobile, with documentation and decision records written alongside the code. From day one I assume someone else will maintain them.

Building systems, and handing them over
Fig. 01Systems built on the assumption that someone else will maintain them: a decision log with the rejected options, an environment reproducible from the repository, tests that actually exclude something.

How I look at it

The cost of a system shows up not at first deployment but at the first change of team. So documentation, decision records and runbooks are part of the product, not a task for the end, and I choose an open stack that can be maintained without any vendor's permission for the system to keep existing. Architecture is dosed here the same way as everywhere: foundations that cannot be added cheaply later, a warehouse identifier on every aggregate, an outbox from the first migration, go in immediately; everything else waits for proof that it is needed.

What I have built

I run more than a dozen production repositories in parallel across two independent ecosystems: Java 21 with Quarkus, Panache, GraphQL, Flyway, and Python 3.12 with FastAPI. Web and mobile applications come from one codebase in a monorepo; around ten systems share one platform with a single identity provider, one PostgreSQL cluster, one reverse proxy and one observability layer. I also go down to the industrial layer: OPC UA to IEC 62541 with my own bridge to the event bus, MQTT with Sparkplug B, telemetry in TimescaleDB. One number shows how the data model evolves: 237 numbered schema migrations in the longest-lived system. Quality is held by tests that actually exclude something: property-based tests for the planning solver, golden tests of the geometry engine with an explicit, deliberate regeneration mode, accessibility tests in the browser and end-to-end tests on physical mobile devices. On a single production system I work in a dozen parallel working copies of branches, the discipline that lets a small practice keep its pace without stepping on its own changes.

What follows

The client is left with a system that can be taken over: decisions and rejected alternatives in writing, an environment reproducible from the repository, no licences that change the billing model mid-year. An engagement you cannot walk away from without harming the client is, in my view, badly designed, so I design mine to be endable.