The Deployment Diagram Is Not the Architecture
A mid-sized insurer runs PolicyHub, a policy administration system built from nine services, two shared databases and three external partner integrations. The architecture is described by a deployment diagram in Confluence and a wiki page last changed two years ago. Teams decide locally: one team added six synchronous REST calls to the claims flow; another reads and writes policy data directly in a shared database. After the last release, p95 claims submission rose from 1.2 s to 4.8 s, and two teams blocked each other for four days. Nobody can say why Kafka was chosen over RabbitMQ, although both are in use. The CTO asks the new architect: 'Is the deployment diagram our architecture? If yes, we are done. If not, what should we document?' A major partner onboarding starts in six weeks and needs stable interfaces.
1. Classify the following as architecture, design or implementation detail in this situation, and justify each: (a) the service decomposition, (b) the six-call synchronous chain in claims, (c) direct shared-database access, (d) the choice of Kafka versus RabbitMQ, (e) a Java utility class for date formatting.
Read the worked answer
Use criteria, not labels: scope, expected lifetime, cross-team impact, effect on quality attributes, cost of change and external visibility.
- (a) Service decomposition: architecture. It defines boundaries, team ownership, deployment units and failure domains. Changing it later affects several teams and operational qualities.
- (b) Synchronous claims chain: architecture. It couples availability and latency: if one of six services is slow, the whole claims submission is slow. The observed p95 rise from 1.2 s to 4.8 s is evidence of an architectural effect, even if the code is local.
- (c) Shared database access: architecture. It creates hidden coupling through a schema and bypasses service ownership. It is hard to reverse and affects consistency, security and deployability.
- (d) Kafka versus RabbitMQ: architecturally significant if it establishes the integration style. The choice affects delivery guarantees, operations, replay, ordering and skill needs. It belongs in a decision record with context and consequences. It is not automatically 'the architecture'; a single-team, easily replaceable use may be design.
- (e) Date-formatting utility: design/implementation. It is local, cheap to change and has no cross-team quality effect.
The deployment diagram is one view. Architecture also includes structures, principles and the significant decisions behind them, including why they were made.
2. What should the architect document first, and what can be deferred, given six weeks and the partner onboarding? Name concrete artifacts and the question each answers.
Read the worked answer
Prioritise by use and risk, not completeness.
First six weeks:
- Context view: what PolicyHub exchanges with partners, customers and internal systems; answers scope and external dependencies for the onboarding team.
- Interface catalogue and contracts: partner-facing payloads, protocols, SLAs, error and versioning rules; answers 'what must we integrate with and what can we rely on?'
- Decision log: Kafka/RabbitMQ, shared databases, synchronous claims calls; each with context, options, decision and consequences; answers 'why is it like this and what may we change?'
- Coarse building-block view: nine services, two databases, three integrations with responsibilities and allowed dependencies; answers 'who owns what?'
- Runtime view of claims submission: the six-call chain, timeouts, failure behaviour; answers why p95 is 4.8 s and where coupling sits.
- Quality scenarios: partner onboarding time, claims p95, availability during partner cutover; makes 'stable interfaces' testable.
Defer: exhaustive class diagrams, full logical data models, every sequence diagram, framework conventions. They are useful to teams but not the first communication need. The rationale is that documentation is a tool for decisions and onboarding; an outdated complete document is worse than a small, owned, current set of views.
3. How should the architect address the shared database and the six-call chain without a big-bang rewrite?
Read the worked answer
Make the coupling visible and reduce it incrementally, with evidence.
- Measure the current path: add tracing and latency budgets per call. Six calls may be acceptable if each has a tight timeout and fallback; the reported p95 of 4.8 s suggests they do not.
- Separate display from commitment. Reads for policy status can use a cache or read model. Writes that enforce policy rules need a clear owner. Direct writes by two teams must be replaced by an API or events owned by one service.
- Introduce data ownership gradually. Pick one contested table, assign an owner, publish an interface and a migration plan. Do not stop all change for a database split.
- Change the call chain where it creates risk. Replace non-essential synchronous steps with events or parallel calls; add timeouts, circuit breakers and bulkheads; keep synchronous calls where an immediate answer is required.
- Record the decision and the exit criteria. For example, reduce claims p95 below 2 s and remove cross-team schema writes within two quarters.
The reasoning is economic: a rewrite risks partner onboarding and delivery, while targeted decoupling addresses the observed quality failures and creates a path for later structural change.