Technical Architecture Decomposition

“EUGH!!! What’s that smell???”
“Shhh! The Architect is Decomposing!”

Let’s talk about Technical Architecture Decomposition.

It’s a mouthful. I think to save keystrokes, I’m going to shorten it to Tech Decomp while we discuss it here. Other authors and sources have called this technique “Detailed Design.”

This is a tool we can use to help our developers understand the scope of a proposed body of work, which in turn lets them give more accurate estimates to each discrete task described within. Once the work begins, it promotes better focus on each discrete part of the project.

Tech Decomp does require an investment of time, but when I’ve used it, it’s paid off in the ways I just described. That said, if you explain what you’re doing and get your other developers on board, it scales wonderfully, and gets them thinking in terms of “what exactly do I need to do to make this change?”

Let’s get into the details.

Why?

• Tech Decomp can help manage cognitive burden for the individuals or teams taking on a complex project.
• It can also provide a new teammate with a smoother path to ramp-up on the project or product team.
• Tech Decomp is valuable whenever you’re dealing with a Junior Hand-Off situation.
  The Junior Hand-Off can apply to anyone, regardless of title.
• You’re integrating a new technology into your system.
• You’re introducing a new architectural concept or pattern to the team
• The requested functionality is significantly different from the team’s core capabilities so far.
• If a requirement carries high operational risk, or a high risk of violating the system’s architecture, a Tech Decomp should be considered mandatory.

If the request is to center a div, that automatically gets 20 story points. No discussion, no tech decomp needed. The largest of the XXL T-shirts should be ordered.

Why Not?

• If a requested change has a very small scope, the Tech Decomp should be skipped.
• If a requested change is very similar to other changes that your team members are already comfortable making and estimating, you can likely skip this exercise.

When?

• Once a Tech Decomp has been identified as necessary, I would perform it between receiving the request and the team discussion when you’re selecting which work items to take on in your next batch of tasks.
• If you’re discussing a set of requests with your team, and it’s determined that you could use a clearer view of the work to be done, a Tech Decomp can be the tool that moves your team from “Oh No I have no idea what that’s going to take” to “Hey, we got this.”

What?

• A Tech Decomp is a detailed view of how a particular slice of your application or system is to be created. This detailed design should include any Operational and Data Contracts for the different components to be built, along with established and documented patterns for inter-component communication when dealing with a composed system.
• Depending on the complexity of the change, whether it is a brand-new system or an extension to existing components, the artifacts of a Tech Decomp will vary according to need. These artifacts may include:
  • Sequence Diagrams
  • Contract Documentation (for both operation and data contracts)
  • A list of components to be altered, with descriptions of how those components shall change
  • Any other documentation considered necessary to communicate the needs to the assigned developer(s).

With practice, this analysis and documentation shouldn’t be overly time intensive. I’ve done Decomps of 8 point stories in an afternoon. This is all subject to familiarity and cleanliness of the codebase, of course. A tightly coupled monolith, or an overly distributed microservice system are going to require a more involved analysis than a cleaner architecture.

Who?

• When you first introduce this concept, it’s best to have your Software Architect or Tech Lead do the decomposition and documentation.
  • To keep from burning that person out, have them train the Senior Development staff in this discipline as they gain their own understanding of the process.
  • Eventually, you can include your more junior teammates in this activity but do make sure that everyone is getting their work peer reviewed.
    As an architect, I like to have my Senior and Junior teammates review my work. It helps ensure that I’m delivering level of clarity they need.

Where?

• If you’re using a work tracking service, you can attach the design documents to the individual work items. (Jira tickets, GitHub Issues, Azure DevOps WorkItems, whatever…)
• Since these documents ARE system artifacts, they should also be incorporated into whatever documentation is included with your code repository.
  README.md files are, in my opinion, a MUST. Put your detailed designs for the different parts of the system into markdown files next to the “root” of the change.

How?

• This is, of course, the hard part, and there is no one thing to school them all. I’ll keep this high-level, broad brush-strokes here and try to capture the basic essence of what you might do for a Tech Decomp.

1. Find the “entry point” to the system where the change will manifest. This usually lives either in the UI or the public API.

2. Trace from that entry point through to the resource access code, keeping notes about each component in the system that must be touched when making this change.

3. Do a second and sometimes even third pass, looking for secondary and tertiary parts of the codebase that will have to change.

• Watch out for any resource definitions that must be changed to affect the request. This includes API Request Objects and Database Schema. Will those artifacts be part of this change?

• If Request Objects and Database Schema are changing, the request just got much riskier, as you must now trace back from those resources through any codebase that depends on them, keeping notes about what needs to change and where.

4. Once you’ve got your list, get it organized into discrete tasks. Don’t give the answers away, just point the developer to where they need to go and give them a general idea of what needs done. (Don’t write the code changes for them, basically.)

Those emphasized bullet points should set off your Spidey Sense. When I get to those places and discover the requested change will incur wide-reaching code changes, I prefer to back away and discuss with the people that made the request. If your work package changes from touching a single service or subsystem to affecting multiple areas of the system, it’s no longer a single “User Story” and requires much more careful planning, sometimes even coordinating with other teams.

The good news about your Spidey Sense starting to tingle is that you’ve found an opportunity to improve the system’s architecture. It may well turn out that redesigning that part of the system into a more suitable architecture would cost less time than making the change “as written.”

Final Thought

And there’s our overview of the Technical Architecture Decomposition concept. Keep in mind that this isn’t the only answer, and I don’t intend for it to be interpreted as “The Way.” This technique is A tool for your workshop, to be pulled off the shelf and used when it will help with specific tasks.

Happy Coding!