Creating an Architectural Vision for Software Engineers
What is an Architectural Vision?
An architectural vision answers the question, “What would we like our architecture to look like in five years?”. Although five is a somewhat arbitrary number, it’s a rough guideline (not too short-term, not too long-term) that makes for the right scope of a vision. The vision can include a specific future state you are working toward, characteristics the architecture should have, and considerations of current and future business needs.
For example, an architectural vision could contain the following elements:
- Service scalability requirements
- Cloud-based or on-prem hosting
- Service-level availability and performance targets
- Support burden considerations (e.g., “can be supported by a team of five engineers”)
- Technology choices (e.g., “Vue3 front-end”)
- Design needs for components or their interactions (e.g., “reusable components”, “decreased susceptibility to network issues”)
There may be specific projects associated with the vision, but it is important to differentiate between the vision and the projects. The vision captures the end state, whereas the projects make up the path to get there. There is usually a feedback loop between a team’s architectural vision and projects, which is to be expected. In summary, your architectural vision can influence what projects you prioritize and the projects you work on can influence the vision. Thus, both an architectural vision and planned projects will almost definitely change over time.
Why Does It Matter?
Throughout my journey as a software engineer, each product, codebase, and team I’ve worked on has led me to the concept of architectural visions. I’ve spent a lot of time with so-called “legacy” code, which gives me an appreciation for organization, documentation, diagrams, and above all, shared understanding among the developers who work together. Those are what I consider the key characteristics of a vision: it is explicitly articulated, every developer working on the project is bought in on it, and it drives forward with deliberate intent. Even newer codebases can quickly devolve into a legacy state when left rudderless.
The reason a vision must be understood by every member of the team is because every member is inherently an agent for change, even the most junior engineer, and that can be either constructive or destructive. For that reason, having one person or an exclusive group of people dictate an architecture, and perhaps not even share the big picture with everyone, is an insidious anti-pattern. It’s much more effective for the team to work together, shepherded by senior engineers. Every member of the team can be empowered to own the vision and make it a reality.
Once the team understands the goals and characteristics of the desired eventual architecture, they can use that information to prioritize the technical debt that matters most and to inform their implementations of business-driven enhancements. It can also act as a hypothesis. A vision-as-a-hypothesis would take the form, “Our architecture should look like ____ to meet these business needs: ____.” When phrased that way, the hypothesis can be “disproven” when business needs change, new information surfaces, or the architecture doesn’t end up having the desired effects. A solid understanding of what problems the architecture is trying to solve means the team can recognize when it’s time to pivot.
Steps to Create Your Team’s Architectural Vision
Drawing on my experience, I’ve formulated a five-step cycle for creating and evolving an architectural vision. However, each step has an immense amount of value on its own. If a team can only understand their current architecture, that is still a worthwhile accomplishment.
Understand Your Current Architecture
Facilitating Team Architecture Conversations
The first step is to gather the team and start building a shared understanding of the architecture as it currently stands. Architecture meetings should aim to produce shareable documentation that can be referenced later and made available to development team members who did not attend the meetings, or who joined the team after these conversations took place.
Meetings quickly lose their effectiveness as the number of participants goes past seven or eight, so it’s important to get the right people in the room. If there are many developers, perhaps spanning multiple teams, prioritize individuals with expertise in the design of the system, decision-makers, and those who will be able to liaise between this group and their development team. After all, even if the entire development team cannot reasonably participate in key conversations, the full team needs to eventually understand the complete architecture and any decisions made for the future vision.
Once you have the group selected, start by establishing the shape of the current system architecture. An excellent way to capture this knowledge is using a system diagram. A system diagram can be built collaboratively by creating it together in a live meeting or, if the system is too large, by tasking subject-matter experts with drafting the section of system that they are most familiar with and then putting the pieces together. For example, you may ask a front-end engineer, owners of services and databases, and an infrastructure engineer to each create a piece of the diagram. Then, in the live meeting, those pieces can be presented, modified, and joined together as others ask questions or clarify the way components interact.
The system diagram is the only aspect of understanding the existing architecture that would apply to all architectural systems. Other group conversations could include creating more detailed diagrams for critical or hard to understand parts of the system, exploring reasons behind certain design choices, identifying vulnerabilities or unnecessary complexity, and discussing how current or planned projects will affect the architecture.
Meaningful Diagrams
Since any diagrams you create in this phase of the process lay the groundwork for the team’s shared understanding of the system and should be understood by current and future members of the team, they need to strike the right balance of conciseness and detail.
One helpful framework for creating diagrams for various levels of an architecture is the C4 model. In this framework, a system is considered at four distinct levels: context, containers, components, and code. Each level “zooms in” on a section of the previous level.
Another strategy to make diagrams meaningful is to annotate the data flow through the system. Often, developers create shorthand diagrams that show two components with an arrow between them, indicating that one calls the other. For example, the following diagram is often used to communicate “X calls Y”, “X uses Y”, or “X depends on Y”.
While this works in some scenarios, if more detail about the interaction between components would be helpful, the arrows can be labelled with what data is moving between components. For the highest level of detail, include arrows for both input and output. In situations where the interaction can be understood with a little more brevity, only the arrow for output can be included. For example, the following diagrams both communicate that X gets a ticker’s price from Y.
This method of labelling the data flow of a system can be used in any level of diagram, from the high-level system context diagram to a component diagram highlighting the interactions for a particular workflow.
Evaluate and Balance Business-Driven Priorities
Once your development team has a deep understanding of the current system, the next step is to understand the business needs that system supports. Although the business and engineering functions of a company may find themselves at odds at times, business needs underly all engineering work. Consider the following aspects of an architecture and how each one requires business knowledge to strike the right balance.
- Scalability
- Expected usage patterns: Total load, burstiness
- Performance requirements
- Data sensitivity
- Maintainability
- Reusability
- Cost
- Business agility
As you balance these priorities, consider the lifecycle stage of your product and how much you understand about its usage and pain points. For a new product, you may want to prioritize business agility to quickly test and validate features. But for a more mature product, you may want to prioritize reliability and scalability. If you know certain parts of the system are more business-critical than others, you may want to focus on reducing vulnerability in that subsystem. If you know your usage is very bursty, you may want to prioritize elasticity.
There is no correct answer for how the business needs of a system should be prioritized since it will always depend on the product. Therefore, evaluating priorities for an architecture cannot be exclusively an engineering activity but must be done with product managers.
Design the Ideal Future State
Equipped with an understanding of the business needs, the strengths and weaknesses of the current system, and upcoming priorities, you are ready to sketch a desired future state. Keep in mind that whatever you come up with will be ever evolving and will always only be a sketch. You can’t set something in stone for five years from now, but you can give yourself and your team something to aspire to. Additionally, there may be aspects of the ideal state that are never attainable because the cost-benefit ratio doesn’t warrant the investment. Try not to worry about that at this point. There may come a time when a partial realization of the idea may be able to be rolled into another project, so it would be worthwhile for everyone on the team to understand what an ideal solution looks like.
If your current state is far from what might be the ideal end state, it could also be helpful to design an intermediary state more ideal than the current. Changes to the system’s architecture will need to happen in steps, so make sure your team will be able to figure out a course of action.
As you make decisions, create architecture decisions records (ADRs) to document your reasoning. ADRs may be intimidating because of their perceived formality, but they don’t need to be. The point is to make sure any current or future development can clarify why a decision was made, and crucially, whether that decision should still stand or can be overturned.
Plot Projects to Move Toward the Ideal State
Once the vision is established, it’s time to get tactical. The best way to maintain momentum and buy-in from the rest of the organization is by planning incremental changes built into the team’s regular work. In that spirit, brainstorm projects that will move the architecture a few steps closer to your ideal state. Come up with at least one, but not too many. You don’t need the entire roadmap of projects to reach the final ideal because it’s almost certain that things will change before the team is able to get through a lengthy list of projects. The goal is just to ensure that everything the team works on takes the system closer to, not further from, something better.
One strategy is to hitch architectural improvements to enhancement work. This means considering whether the implementation of a feature that was already prioritized for development can help shift the architecture toward your more ideal state. It’s the same idea as refactoring code as part of regular development. Even though doing so may increase the time-to-market for the feature, it’s worth the investment. The cumulative effect of refactoring or rearchitecting during regular development, instead of contorting features into the existing system, is achieving the previously evaluated business goals of your system’s improved architecture.
Another approach is to plan dedicated projects for architectural refactoring. Although this approach can be harder to explicitly tie to business value, since users may not notice any difference, you have the list of business priorities that the new architecture is meant to achieve. When taking this route, make sure to document (perhaps with an ADR) the expected outcomes and how success will be measured. Provide clear key performance indicators (KPIs) and keep the project tightly scoped to ensure that it is a productive use of the team’s time.
You will most likely need a combination of strategically executed enhancement work and dedicated architectural projects throughout your journey. Resist the temptation to do all the rearchitecting upfront. Working toward an architectural vision should be a slow-and-steady, indefinitely sustainable process that allows your system to adapt to continuously evolving requirements over time.
Evolve the Vision Over Time
Inevitably, the premises of your original vision will change over time and what was projected as an ideal design will no longer be so. There could be many reasons for this, including changing business needs, new technologies, resources available to your team, and emerging opportunities for shared solutions with other parts of the organization.
Even though aspects of the vision will be invalidated and discarded, it’s still worthwhile to go through this process. Firstly, collaborating with the development team to build a shared understanding of the system and to dream of something better is invaluable. It builds trust and empowers all developers to take ownership of the system’s quality. Additionally, having a loose vision laid out will allow you to recognize when it’s time to adjust course. That’s what evolving the vision is: continuously taking stock of the strengths and weaknesses of the architecture, considering upcoming priorities and projects, and tweaking your plans as appropriate.
Conclusion
An architectural vision is a tool that can steer your development team toward continuous improvement of your software system. One of the biggest benefits of articulating a clear vision is unleashing the creative power of all the people on the team to work in incremental changes in every piece of work they do. Therefore, it’s essential to understand the current system and its strengths and weaknesses and to determine what outcomes are needed from improvements to the architecture. When a team has a shared picture of the desired end state, how the planned projects can bolster progress toward that ideal, and how to adjust course, the legacy of an architectural vision will far outlast any individual team member or initiative.
Author: Jennifer Ma (Principal Software Engineer)
Reviewer: Franchesca Dutra (Lead Sales Engineer) & Josh Gaddy (VP, Director, Developer Advocacy)
