4 Steps to Analyze and Document Software Architecture

Have you ever joined a technology company and got lost in the code base trying to reverse engineer what was happening? What about a time when you were baffled why the system was designed the way it was? What if you are starting a new design, where do you even begin!

In this post, I will describe a simple approach that outlines 4 steps:  Problem, Analysis, Solution, and Plan. These steps should outline the blueprint for how to approach software architecture. A good blueprint should help you be methodical in your design approach,  convince others of your design decisions, and ultimately help future-you recall why you did what you did and the tradeoffs :)

Software architecture is not a diagram of boxes and arrows or a set of technology choices. A good architecture will connect people in your team and organization as much as it connects services and databases. I would claim that software architecture is not really about documenting technical problems, instead, it is about documenting how we solve people’s needs with technology. The “people” part is very crucial. Changes to architecture should be viewed as having a large “blast radius” and thus require more consideration and wider communication with all stakeholders.  Architecture evolves and emerges in agile processes which makes continuous communication important.  One last thing, architecture is the art and science of simplifying complexity.

Problem

This step focuses on the problem definition. Get to the user’s needs and wants and not how to address them yet. The following subsection should help flush out the details you need.  You could reference the relevant product documents so as to not duplicate that information again. However, I highly recommend summarizing your understanding and listing the key functionalities here still.  This will be the basis for your analysis and solution tradeoff.  Use the following questions to guide you.  It is ok to ignore some questions if they are irrelevant in your context.  At least be intentional about why you won’t cover them as opposed to just forgetting about it.

Context

Describe the background for the project.

• Why are we doing this? Why now?
• What happens if we do not do anything?
• How do we know if we solved the problem?
• Who are the stakeholders and what is their stake exactly?

Functional Requirements

Describe the utility expected by the users.

• Who are the users and what roles do they play?
• What are the expected use cases? 
• What information needs to come from users?
• What is a must and what is a nice-to-have?

Constraints

Describe the boundaries we need to stay within.

• Do we have to adhere to certain standards?
• Do we need to be compliant with certain regulations?
• Any technologies we must integrate with that are mandated by users?
• Any deadline we must meet?

Out of Scope

Sometimes it is better to describe the scope by stating what is outside the scope.

• What are the things we intentionally won’t be considered in this architecture?
• Why you won’t consider them?
• Are there parts of this problem owned by other teams?

Analysis

After defining the problem and before diving into the solution space, it is important to take a step back and analyze what you learned so far.  The analysis step is still in the problem space but now we can bring our own point of view and structure to the problem. Think of the nouns and verbs as well as the inputs and outputs described by users and the product team.  Can you simplify and bring order to the chaos? Are there explicit assumptions? The analysis phase might push you to go back to refine the problem definition and have a constructive discussion with the product team and/or user base.

System Context

Apply the system thinking approach to better understand the context of the system

• What are the boundaries of the system?
• What is considered inside vs outside the system?
• What are the functional components within the system?

Domain Analysis

Consider principles of Object-Oriented Design and Domain-Driven Design.

• What are the domain objects in our system?
• What is the relationship between them?
• What fields define uniqueness, immutability, and of what type?

System Qualities

Establish the non-functional requirements of the system.

• Which *ilitities should you consider: Availability, Scalability, Security, Maintainability, Testability, etc.)?
• What metrics will we use to define the system’s qualities?
• What are their priorities so we can do a trade-off?

Solution

Describe the proposed solution(s) and their tradeoffs. Include enough detail to allow for productive discussion and comments from readers.

Architecture Diagram

Diagrams are an important communication tool. Ensure consistency of visuals and perspective.  Consider component and connector diagrams along with dataflow or sequence diagrams as you see fit.  Elaborate on the technology stack and tools to be used if relevant.

System Quality Tradeoffs

Remember that if you have alternative solutions, all of them must meet the functional requirements.  The variation in solutions will only have non-functional tradeoffs.  Discuss tradeoffs between the alternative solutions and explain your decision on which solution you will adopt.  You can use “Architecture Decision Record” style documentation if you wish.

Cross-Cutting Concerns

Address cross-cutting concerns like logging, monitoring, security, testing, etc. in this section

Plan

A solution that can’t be implemented and delivered to customers is not useful. Consider how to break the work down into milestones.  This requires working closely with the product team to ensure that the incremental delivery is customer-centric, not technology-centric.  The solution section describes the end goal.  The plan section describes how to get there from where we are now

Success Criteria

Ensure that everyone is clear on what success means.  Is there a minimum set of functionality or quality that must be met or is it time-based where a certain deadline must be met?

• What defines success for this project?
• What constitutes failure?
• What is the minimum to be delivered to declare success?

Risks

Reflect on what could prevent you from succeeding. When listing risks consider their impact and likelihood.  Then for top risks think of possible mitigation. The key categories of risk include ambiguous requirements, unknown or unproven technologies, and resource availability.

• What could impact your ability to meet the success criteria?
• What could delay the project schedule or result in overspending?
• Do we have enough people with the right skills?

Milestones

This could be tracked in some project tracking tools (JIRA, Asana, ZenHub, etc.). The goal is to figure out the phases for how to get to what the proposed solution suggests.  Big bang projects are doomed to fail.  Be clear on what are the deliverables and scope of each milestone and ensure it is measurable. Estimate required effort as well for each milestone to double-check if everyone has the same understanding of the solution and goal.

• Does each milestone provide customer value (demoable or shippable)?
• Is the team in agreement on the major deliverables needed?
• Is there a major discrepancy in team estimation for the major deliverables?

Open Questions

Track any unresolved questions about the proposed solution here.