What architects actually do
An architect's real output is decisions: the few choices that are expensive to change, made with honest trade-offs and carried by people who do not report to you. This lesson gives you a test for which decisions are yours, the difference between software, solution and enterprise architects, and a way to lead without a manager's authority.
By the end you can
- Tell an architecturally significant decision from an ordinary one with a four-question test and a cost-of-change estimate
- Explain what software, solution and enterprise architects decide, and how their decisions fit together
- Write a trade-off record with real options, what each one gives up, and a trigger to revisit
- Get decisions adopted through clear decision rights, early advice and written reasoning
- Start a decision log and a triage routine for Mangrove's back-office move
The everyday picture
Think about how a city grows. Families design their own houses: the kitchen, the paint, where the sofa goes. Nobody at city hall cares, and a family can change its mind next year.
A district planner decides other things: where the roads go, where the water pipes run, which blocks are for homes and which for shops. Those choices are cheap on paper and very expensive later. Once a hundred houses sit on a road, moving it means tearing them down. The planner also does not build the houses. The planner's job is to agree the few things everyone must share, write them down, and convince the builders to follow them.
Above the district there is a regional plan: one power grid, one set of building codes, one road numbering scheme for the whole region. Software works the same way. Software architects shape one building, solution architects plan a district of systems that must work together, and enterprise architects keep the region coherent. In every case the job is the same: find the decisions that are hard to undo, make them well, and help other people live with them.
Architecture is the decisions that are expensive to change
There are many definitions of architecture. The most useful one for daily work comes from Grady Booch: architecture is the set of significant design decisions that shape a system, and "significant" is measured by cost of change. Martin Fowler's essay "Who Needs an Architect?" makes the same point: architecture is the important stuff, the things people find hard to change later.
This gives you a method. Every week, engineers make hundreds of design decisions. Most are cheap to reverse: a variable name, a screen layout, a library inside one module. If a team gets one wrong, it fixes it next sprint. A few decisions are different. They cross team boundaries, lock data into a shape that many systems depend on, or decide how fast or reliable the whole system can be. Those are architecturally significant decisions, and they are the architect's job.
To sort decisions quickly, ask four questions:
- Teams. Does it affect two or more teams, or an outside party such as an agency or a partner?
- Reversal. Would undoing it take an engineer-month or more?
- Data. Does it change data that other parts share, or data you must keep for years?
- Qualities. Does it move a quality attribute the business has a target for, such as speed at peak or availability?
Two or more yes answers: treat it as architecture, with options, a written record and a review. Zero or one: the team decides and writes one line in a shared log. One exception: a decision that would take six or more engineer-months to undo is a one-way door even if nothing else applies, so it gets the full treatment. These thresholds are a rule of thumb you tune to your company, not an industry standard.
Cost of change is easy to estimate roughly. At Mangrove an engineer costs about $5,000 a month. Renaming a label on the Store app takes about a day, roughly $250. Splitting a table that four teams read takes maybe three engineers for two months, about $30,000, plus the risk of breaking store operations along the way. The numbers do not need to be precise. They need to show which decisions sit in which order of magnitude.
Quick check
Which of these is architecturally significant at Mangrove?
Direct table access ties an outside team's app to the back office's internal schema: two parties, shared data, and months of work to undo once the Partner app depends on it. The button colour and the private function are cheap to change and affect one team, so they stay with that team.
Three roles: software, solution and enterprise
Job titles vary a lot between companies, and in a small company one person may do all three jobs. The useful difference is the scope of the decisions and the time horizon.
- A software architect works inside one system. Decisions: the module structure, where boundaries sit (Monolith, modular monolith, microservices), the main patterns, how the code meets its speed and reliability targets. Horizon: weeks to months. Usually a senior engineer who still writes and reviews code.
- A solution architect works on one business change that spans several systems. Decisions: which systems change, how they connect, who owns which data, what to build or buy (Build, buy or partner), and the migration path. Horizon: six to eighteen months. This is your role in this course.
- An enterprise architect works across the whole company. Decisions: the portfolio of systems, shared standards (one identity provider, one cloud, one way to log), which business capabilities get their own systems, and the multi-year roadmap. Horizon: three to five years. Frameworks such as TOGAF, from The Open Group, describe this level.
The levels connect in both directions. Enterprise standards are guardrails for solutions: you design within them, and when a standard truly cannot work for one part, you ask for an exception with evidence instead of quietly ignoring it. Solutions in turn set guardrails for each system: the contracts between them and the data each one owns. Inside those, the software architect and the team are free. Information also flows upward. A solution architect who finds that the standard database cannot meet a reporting need tells the enterprise level, so the standard improves for everyone.
Quick check
Head office has a standard that every app signs users in through one identity provider. You are the solution architect for the back-office move. What is your job here?
Enterprise standards are guardrails for solutions. You work inside them and raise exceptions openly with evidence, so the standard can improve. Quietly choosing another provider breaks the coherence the standard exists for, and the enterprise level sets the rule without designing every solution.
Trade-offs: better for these needs, at this cost
An architecture is only better or worse for a given set of needs, constraints and budget. So an architect's main tool is the honest trade-off. A trade-off record has five parts:
- The decision and its driver. One sentence, and the business need or quality target that forces it. (Turning vague needs like "fast and reliable" into numbers is the subject of Quality attributes and constraints.)
- Real options. At least two serious ones, plus "keep what we have". A list with one real option and two straw men is a sales pitch.
- What each option gives and costs. Score each against the same quality attributes, and add the cost to build, the cost to run and the cost to reverse.
- The decision and what you accept. Write the downside you are choosing to live with in plain words: "Partner app stock can be up to a minute behind."
- A revisit trigger. A measurable condition that reopens the decision, so it is not argued again every month and not kept forever by habit.
Here is a real example from Mangrove's back office. Today Lagoon Digital's Partner app reads stock levels straight from the back office's shared tables. Every time the back office changes a column, the Partner app risks breaking, and Lagoon releases on its own schedule. The options:
| Option | Gives | Costs and risks |
|---|---|---|
| Keep direct table reads | Nothing to build; stock is always current | Any schema change can break partner ordering; no one owns the contract |
| A stock API owned by the stock module | One versioned contract; back office can change its tables freely | About 1.5 engineer-months ($7,500); Lagoon must change its app; a call per screen |
| Stock-change events the Partner side consumes | Loose coupling; partner screens stay fast if the back office is slow | About 2.5 engineer-months ($12,500); stock a few seconds behind; needs an outbox (Events, the outbox pattern and sagas) |
None of these is right in general. If partner shops order mostly the evening before delivery, a few seconds of lag do not matter and events win on resilience. If they check live stock before every order line, the API may be the better first step. The trade-off record makes that dependency visible, so the business owner can confirm the fact that decides it. The detailed design of APIs, events and data ownership is the subject of Integration and data ownership.
Quick check
Which of these is a complete trade-off record?
A complete record names what you give up and when you would change your mind. The first is a slogan with no options. The second compares options but hides the accepted downside and has no trigger, so the same debate returns every few months.
Influence: getting decisions adopted without authority
Most architects manage nobody. The engineers who build the system report to an engineering manager, the agency answers to its contract, and the business sets priorities. A decision that nobody follows is worth nothing, so a large part of the job is influence. Three practices make it work.
Make decision rights explicit. Write down who decides what, so nobody has to guess and nobody waits for the architect. A team decides anything inside its own module. The solution architect decides contracts between systems and data ownership, after hearing from the affected teams. One-way doors, such as a new database engine or a multi-year vendor contract, go to an architecture review where the engineering manager signs off. When rights are clear, most decisions move fast, and the slow, careful process is kept for the few that need it.
Seek advice before you decide. Andrew Harmel-Law describes the advice process: anyone may make an architectural decision, as long as they first ask everyone meaningfully affected and the people with relevant expertise, and record the advice. You do not have to follow every piece of advice, but you must hear it. People support decisions they helped shape, and the advice often finds the flaw before it costs money.
Translate between floors. Gregor Hohpe calls this riding the architect elevator: from the engine room where engineers work to the top floor where managers decide budgets and priorities. To Ken you say "this change cuts receiving freezes from twice a quarter to none, for about $5,000". To engineers you say "reports move to a read replica, so the stock tables stop fighting the report for locks". Same decision, two languages.
Finally, stay close to the code. Architects who never see the system lose credibility and start designing for an imagined one. Keep a small, regular hands-on share: reviewing pull requests that touch boundaries, building short spikes to test a risky option, pairing with a team during a migration. Write everything that matters down. A written decision outlives the meeting, travels to people who were not there, and stops the same argument from coming back. Remember too that team boundaries and system boundaries pull on each other (Conway's law, in Monolith, modular monolith, microservices), so a boundary you draw on a diagram only holds if a team owns each side of it.
Build it
We will set up the architect's basic toolkit for Mangrove's back-office move: a decision log, a cost-of-change estimate, a trade-off record and a decision-rights table. Keep them as Markdown files in the back office's repository, next to the code.
-
Start a decision log
One file, one row per decision, triaged with the four questions. Rows marked "architecture" get a full ADR later (the format is covered in Running a design review and in depth in Decisions, diagrams and reviews). Save it as
docs/architecture/decision-log.md.Markdown# Back-office decision log | # | Decision | Teams | Undo (eng-months) | Shared data | Quality target | Route | Owner | |----|---------------------------------------|-------|-------------------|-------------|----------------|--------------|------------| | 1 | Where stock reports read their data | 3 | 1 | yes | receiving p95 | architecture | architect | | 2 | Partner app access to stock | 2 | 3 | yes | partner orders | architecture | architect | | 3 | Release cadence and module boundaries | 4 | 6 | no | lead time | architecture | review | | 4 | Which module owns an article's price | 3 | 2 | yes | price latency | architecture | architect | | 5 | Date picker library for buyer screens | 1 | 0.1 | no | none | team | buying team| | 6 | New column on the stock report | 1 | 0.05 | no | none | team | data team | Route rule: 2+ yes answers, or 6+ engineer-months to undo = architecture. -
Estimate the cost of change
A rough estimate in engineer-months turns "this is risky" into a number managers can compare. Write the assumptions next to the result.
OutputAssumption: 1 engineer-month = $5,000 (salary and overhead, rounded) Decision 2: move Partner app from shared tables to a stock API Build the API in the stock module 1.0 eng-month Lagoon Digital changes the app 0.5 eng-month (their estimate, billed to us) Run both paths for 4 weeks, then cut 0.3 eng-month Total 1.8 eng-months = about $9,000 Cost to reverse later, once 1,800 shops depend on the API: remove API, re-point the app, retest about 2 to 3 eng-months = $10,000 to $15,000 Cost of doing nothing: every back-office schema change needs Lagoon's review and a joint release (about 1 extra week of delay per change) -
Write the trade-off record
For each architecture row, a short record with real options, what you accept and when you would revisit. This becomes the body of the ADR.
Markdown## Decision 1: where stock reports read their data Driver: the stock report has twice frozen goods receiving (about 1,280 deliveries a day). Target: receiving stays fast while any report runs. | Option | Build cost | Run cost | Freshness | Reversal | |---------------------|------------|-----------------|------------|-----------| | A. Tune the query | $2,500 | none | live | easy | | B. Read replica | $5,000 | replica bill | seconds | easy | | C. Data warehouse | $15,000 | warehouse jobs | up to 1 h | medium | Decision: B now; plan C for month-end finance reports next quarter. We accept: reports can be a few seconds behind the stores. Advice from: Nadia (engineering), Tomás (data), two store managers. Revisit if: replica lag passes 30 s at p95, or finance needs cross-system reports that the replica cannot serve. -
Publish decision rights
One table that says who decides what, so teams never wait for you on things that are theirs.
Markdown## Who decides what (back-office move) | Kind of decision | Decides | Must ask first | |---------------------------------------------------|--------------------|---------------------------------| | Anything inside one module | The owning team | Nobody (log it) | | A contract between modules or with the Partner app| Solution architect | Both teams, Lagoon Digital | | Who owns a table or an event | Solution architect | Every team that reads it | | One-way doors (new database, vendor, 6+ months) | Architecture review, Ken signs | Affected teams, finance | | Exceptions to company standards | Enterprise level | Solution architect brings evidence |
Bring it to your team
Ask these when a decision lands on your desk or comes up in a design review.
- "Which teams, outside parties and data does this touch, and what would it cost to undo in a year?"
- "What are the real options, including keeping what we have, and what does each one cost to build, run and reverse?"
- "What downside are we accepting, in one plain sentence?"
- "What measurable change would make us revisit this?"
- "Who has been asked for advice, and who will live with this decision every day?"
- "Is this ours to decide, or does a company standard already cover it?"
Red flags
- A design presented with one option, or with options nobody would seriously choose
- Big decisions that exist only in someone's memory or a chat thread
- Every small choice waiting for the architect's approval
- A target diagram drawn without talking to the teams who will build it
- "We use X because the big tech companies do" with no link to Mangrove's own needs
Practice
Triage the decision log in code
Write triage(decisions, engineerMonthly). Each decision has id, teams (number of teams or outside parties affected), reverseMonths (engineer-months to undo), sharedData and movesQuality (booleans). Count the yes answers: two or more teams, one or more engineer-months to undo, shared data, and a moved quality target. The route is 'architecture' for 2 or more yes answers, or for 6 or more engineer-months to undo; otherwise 'team'. Return, in input order, { id, route, reverseCost }, where reverseCost is reverseMonths times engineerMonthly, rounded to whole dollars. The starter gets the thresholds wrong.
function triage(decisions, engineerMonthly) {
return decisions.map((d) => {
let yes = 0;
if (d.teams > 2) yes++; // more than two teams?
if (d.reverseMonths > 1) yes++; // more than a month to undo?
if (d.sharedData) yes++;
if (d.movesQuality) yes++;
return {
id: d.id,
route: yes >= 2 ? 'architecture' : 'team',
reverseCost: d.reverseMonths * engineerMonthly,
};
});
}test('a cross-team decision on shared data goes to architecture', () => {
const out = triage([{ id: 'report-source', teams: 3, reverseMonths: 1, sharedData: true, movesQuality: true }], 5000);
expect(out[0].route).toBe('architecture');
});
test('exactly 2 teams and exactly 1 month to undo both count as yes', () => {
const out = triage([{ id: 'release-cadence', teams: 2, reverseMonths: 1, sharedData: false, movesQuality: false }], 5000);
expect(out[0].route).toBe('architecture');
});
test('6 or more months to undo is a one-way door on its own', () => {
const out = triage([{ id: 'db-engine', teams: 1, reverseMonths: 8, sharedData: false, movesQuality: false }], 5000);
expect(out[0].route).toBe('architecture');
});
test('one yes answer stays with the team', () => {
const out = triage([{ id: 'date-picker', teams: 1, reverseMonths: 0.1, sharedData: true, movesQuality: false }], 5000);
expect(out[0].route).toBe('team');
});
test('reverseCost is rounded to whole dollars and order is kept', () => {
const out = triage([
{ id: 'a', teams: 1, reverseMonths: 0.3, sharedData: false, movesQuality: false },
{ id: 'b', teams: 1, reverseMonths: 0.05, sharedData: false, movesQuality: false },
], 4999);
expect(out).toEqual([{ id: 'a', route: 'team', reverseCost: 1500 }, { id: 'b', route: 'team', reverseCost: 250 }]);
});
Show a solution
function triage(decisions, engineerMonthly) {
return decisions.map((d) => {
const answers = [
d.teams >= 2, // two or more teams or outside parties
d.reverseMonths >= 1, // a month or more to undo
d.sharedData === true, // shared or long-lived data
d.movesQuality === true, // moves a quality target
];
const yes = answers.filter(Boolean).length;
const oneWayDoor = d.reverseMonths >= 6;
return {
id: d.id,
route: yes >= 2 || oneWayDoor ? 'architecture' : 'team',
reverseCost: Math.round(d.reverseMonths * engineerMonthly),
};
});
}The thresholds are "two or more" and "one or more", so they need >=. The six-month rule catches one-way doors that one team could choose alone, such as a new database engine. Rounding matters because months times a monthly rate is rarely a whole number: 0.3 months at $4,999 is $1,499.70.
Sort Ken's list and write one trade-off record
Ken forwards six questions about the back office: (1) whether buyers' price changes reach the Partner app through an API or nightly files; (2) which charting library the buyers' dashboard uses; (3) whether to move the whole back office to a different database engine; (4) the wording of an error message on the GRN screen; (5) who owns the article table that buying, stores and finance all update; (6) whether the back office keeps monthly releases or moves to weekly. Triage each with the four questions, then write a trade-off record for question 5.
- Questions 2 and 4 stay with the owning team; 1, 3, 5 and 6 are architecture, and 3 is a one-way door
- Each triage answer names which of the four questions are yes
- The record for question 5 has at least two real options plus "keep what we have"
- Each option has a rough cost in engineer-months or dollars, and what it gives up
- The record states the downside accepted and a measurable revisit trigger
- It names who you would ask for advice before deciding
Show a model answer
Triage
1 Price changes to Partner app: teams 2+, shared data, moves price latency -> architecture
2 Charting library: one team, cheap to undo -> team
3 New database engine: 6+ eng-months to undo, all teams -> architecture, one-way door, review
4 Error wording: one team, a day to change -> team
5 Owner of article: 3 teams, shared data, months to untangle -> architecture
6 Release cadence: 4 teams, moves lead time -> architecture
## Decision 5: who owns the article table
Driver: three teams update article; a change by one broke the others twice.
Options
- Keep shared ownership: $0 now; breakages continue
- Catalogue module owns it; others call its API: about 2 eng-months ($10,000);
stores and finance must stop writing directly
- Split: catalogue owns core fields, pricing owns prices: about 3 eng-months
($15,000); two owners to coordinate
Decision: catalogue module owns article; prices move to pricing later.
We accept: finance waits for an API change to add a field.
Ask first: buying, store ops, finance, Tomás (reports read article).
Revisit if: more than 2 API change requests a month wait over a week.Check yourself
Ken asks you to "pick the best database" for the new pricing part of the back office. What is the most useful first reply?
A database can only be judged against named needs and constraints, so the first step is to find those needs. Familiarity and big-company fashion skip the trade-off entirely, and handing the choice to one consumer gives a cross-team decision to a party that only sees its own side.
Two years ago the team recorded the decision "all reports run on the primary database". Orders have since tripled and reports now slow down goods receiving. What should you do with the old decision?
The old decision was reasonable in its context; the context changed. A new record that supersedes it keeps the history honest and shows why the system moved. Editing or deleting hides the reasoning, and refusing to reopen it ignores exactly the kind of change a revisit trigger exists for.
The Store app team and finance disagree about whether stock adjustments must reach the back office instantly or by end of day. You manage neither team. What fits the architect's job best?
Architects lead through written trade-offs and early advice, and the business owner decides when the trade-off is about business value. Escalating to authority wins the meeting and loses the teams. Building both doubles the cost and the confusion, and deadline order says nothing about which option meets the need.
Flashcards
Key takeaways
- Architecture is the set of decisions that are expensive to change. Triage every decision with four questions and send most of them back to the teams.
- Software, solution and enterprise architects differ in scope and time horizon; each level sets guardrails for the next and stays out of the inside.
- A trade-off record has real options, costs to build, run and reverse, the downside you accept, and a measurable trigger to revisit.
- Influence beats authority: explicit decision rights, advice before deciding, decisions in writing, and the same decision explained in business and engineering terms.
Sources
- Who Needs an Architect?, Martin Fowler, IEEE Software, 2003
- Scaling the Practice of Architecture, Conversationally, Andrew Harmel-Law, martinfowler.com, 2021
- The Software Architect Elevator, Gregor Hohpe
- The TOGAF Standard, The Open Group