Software Architecture: Why We Decided It This Way

Alexey joined as a lead programmer and spent six years on the integration bus: IBM products, enterprise integration in full, transforming and shuttling data between sources — first products for individuals, then application processes for legal entities. About a year in he looked at what the other architects in his unit did, decided he could do the same or better, and moved into the role he has held for nine or ten years. He left the integration layer because the effect was invisible: output is easy to count — how much data flew through your pipes each way — but the outcome for the end customer was far away. He went round the teams looking for where an architect was needed and was caught by a person from the business who described the pain outright: we cannot cope, we are dying. That was Alexander Pavlyuk, and Alexey gave the next five years to product architecture in that business line.

It started with one team; six months later he was told he was doing well and given seven more. Seven teams means at least seven products, possibly twelve, so the approach had to change radically. Alexey placed himself at the level of the cross-system landscape — which protocols to use, where the data lies, where it is best taken from — and left low-level architecture to mature senior engineers. Documentation had to be introduced because there was none: they picked C4 for its simplicity and for not being overloaded, unlike the heavy enterprise modelling languages, which at this scale have nothing to cover. A repository of diagrams appeared, part of the work was automated, a portal came up where the whole architecture is visible, and an approval process with it. Nobody handed him tooling: if you are so clever, write it yourself, show the result, then we will see. The rollout was gentle and backed by management, starting with the more willing teams, and Alexey did much of the review work for them himself.

The teams asked for ADRs themselves: you drew the architecture, well done, but why this one is unclear. There are no standards, by Alexey's reckoning, though there are plenty of templates; they looked at how different companies do it and assembled their own, solving strictly their own problems. First the functional requirements are written out and ranked by complexity and business impact: the architect estimates the rough complexity, the business the need for the feature, and something can be dropped, something postponed, something never done. Then come constraints — regulatory ones, when the central bank requires a bank to build something new urgently — and security risks, which rule some solutions out. Alternatives are proposed for each requirement and compared by pros and cons, and the decision reads: I pick this one because its pluses close such-and-such requirements, and I can live with such-and-such minuses. Design turns out iterative: on the next requirement the chain of decisions falls apart and it all starts again.

RFCs and ADRs have taken root across the company, each unit with its own template but the same essence. The value of the log shows up a year later, when a new requirement fits nowhere: without the record it feels as if someone once blundered, while with it you can read the starting context and conditions. Alexander recalls showing the skyscraper metaphor at a business stand-up and explaining why it is poor for software: an investor rarely turns up halfway through construction asking for the second half to be rotated ninety degrees — yet in software that happens regularly. Alexey adds that the benefit is visible here and now: the developer thinks while writing and brings a finished document to build the discussion around, so fewer meetings are needed. Alexander adds that the template also levels up the engineers: a senior colleague gives feedback like a coach, flagging open questions rather than mistakes. The hardest thing to defend was documenting decisions at all: teams lived by the self-documenting-code paradigm, yet cross-system links over core banking services cannot be caught through code. By the third ADR nothing needed selling any more.

Today the process works one way or another across the whole business line: in Alexey's unit two people cover about twenty-two teams, roughly eleven each, plus another five teams apiece in a unit with no dedicated architects, where they help with reviews. He will not count products by the piece — the business is big, so they arrived at the concept of services, which makes it easier to judge what exactly the user gets. Dogfooding barely works in this segment: engineers are rarely company owners or sole traders, without the right legal status you cannot get access, and they do not use these products daily anyway. So knowledge about the product has to be mined through practices: discovery first, then event storming — domain experts and developers at a board sticking up event notes, laying them out on a timeline and running the flow backwards to find what was missed.

The practice was invented by Alberto Brandolini; he published the book on Leanpub and, by Alexey's account, never finished it, while the community adapted what was there and added its own sets of stickers. One of the most striking sessions was on the HR domain: people came from recruiting, employee development, support and analytics, all saying "candidate" and all meaning something different, and follow-up questions showed that not everything called a candidate is one — but the contexts and subdomains drew themselves. The participants note that a developer who sees the whole process suggests removing extra steps, and the business goes off to the lawyers to ask whether that is allowed. Alexey outlines the pitfalls himself: on a simple area it is a cannon firing at sparrows, and on a technical platform it is hard to separate a technical event from a domain one. They sold the practice like a mini-startup: did it, showed management the result, ran internal courses and wrote up a step-by-step template — first in Miro, later in an in-house tool. Learning, he advises, should follow a concrete task: that is how he first picked up Python, when he needed metrics on architecture reviews.