How to make sense of your current architecture?

What is your architecture? This is the fundamental question for many in engineering. Especially people who join an engineering team that has working software. This question seems very simple and a logical one. Surprise surprise every company I have been at, this simple question has been the hardest question to answer.

First you ask your peers or your manager, then you slowly work your way up to your Chief Architect and CTO. I bet you the answer will be very different based on who you talk to, leaving you with more questions than answers.

Why is it so hard to get a definitive answer to this question? This is the second logical question you would be asking before you give up and get on with the routine or just writing code based on your limited knowledge and being apart of the broader feature factory.

Let me try to take a stab at answering why it is hard. As a software company evolves with time, some of the knowledge is lost to attrition, systems have evolved beyond their creator, documentation has gotten stale, and the engineering organisation has become a feature factory to serve the ever growing demand for new features that needs to be shipped yesterday.

Any fool can know. The point is to understand. - Albert Einstein

Don't be surprised if no one has the answer to the above question of what the current architecture is. Most of the time none of the developers really know why we do things the way we do them. New engineers jump in to writing more code than asking these first principle questions or trying to make sense of the current architecture. People who cannot get answers just leave after 6 to 12 months in frustration. These are the people who you should keep. This article is written for these people who care about what they do and they don't know how to find the right answers.

No matter what your title is, if you are part of the engineering team it is important to make sense of the current architecture and understand why certain things are done the way it is done. These questions unanswered and unchecked could become an architectural ticking time bomb waiting to explode with serious business consequences. Engineers who just code without asking any questions are adding to the technical debt and even may be adding to architectural and conceptual depth making it really expensive and hard to fix in the future.

No architecture is perfect and there is no one size fits all architecture. I have seen successful businesses build on monolithic architectures to micro service based architectures. It is important to make sense of the current architecture in order to help make future decisions to evolve your tech stack to meet the future demand. You have to know the past and the present to make the right decisions for tomorrow.

How do you make sense of the current Architecture?

I suggest to follow these 3 simple steps to get a sense of the high level architecture and how it interacts with each of the underlying systems.

1. Use the product like a customer would and talk to non tech teams by asking questions about the underlying systems
2. Understand the history of the company evolution - Ask your most tenured colleagues
3. Build a Context Map of the business to get a high level view of the architecture

I am sure many onboarding programs will cover the system architecture and best practices. This is not enough as most of the time the architecture has evolved beyond what is documented.

Use the product like a customer would and talk to non tech teams by asking questions about the underlying systems

1. Best way to understand the current architecture is to start with a demo of the product we sell to our customers. it is important to understand why customers like our product and buy it. This will give you a good understanding of the USPs and value proposition of the product you are building.
2. Talk to customers and understand why and how they use our product to get an appreciation of how the customer experiences our product. This will enable you to get a deeper understanding of the value proposition.
3. Use the product like a customer would and build a mental model of the different systems involved to make the user journey what it is. It is also important to understand and experience how customer support and operations run to get a good perspective of different stakeholders and how they use the product to serve the end consumers.
4. Talk to non tech teams and ask questions about underlying systems that support the current customer experience. Understand deeply on how these systems work with each other from a non tech team perspective is important to get a non biased objective view. Get to know the good, the bad, and the ugly so you have a good understanding of what needs improvement or fixing.
5. Why not ask these questions from engineering teams instead of non tech? Non tech teams are more closer to the reality than the engineering teams are. Non tech teams can provide an objective view of the system as they see it without any ego and emotions attached to it.

Understand the history of the company evolution - Ask your most tenured colleagues

1. It is easy to criticise a system and find all faults with the architecture. If you truly want to make sense of the current architecture, it is important to look at the evolution of the platform through the startup journey.
2. Understanding the past would allow you to get a quick history lesson into the company on how decisions were made and what circumstances drove to make certain decisions. These data points will help appreciate the current architecture and the fact that you have a job and most importantly will allow you to have the knowledge to steer the architecture towards the future avoiding some of the same pitfalls in the future.
3. This knowledge is not easy to obtain, need to go talk to the most tenured colleagues in the company. Knowing your history through the eyes of different stakeholders will allow you to move on to the next level to complete the big picture architecture.

Build a Context Map of the business to get a high level view of the architecture

1. Context Map is a tool you can use to visualise all your different systems or bounded contexts and how they are related to each other. I will do a separate writeup on bounded contexts, for now lets imagine these are just independent systems you have in your enterprise.
2. A large scale enterprise system or platforms consists of multiple systems, therefore multiple bounded contexts.?These bounded context’s integrate and relate together. This mapping of relationships and integrations across a large scale system is referred to as the Context Map of the system in question.?
3. A Context Map captures the existing terrain in the Enterprise. A mapping of the present NOT the future. Once you create the initial Context maps you will start to establish an initial system level architecture across the enterprise.

By the end of this exercise an engineer should know at a high level what the architecture of the enterprise would look like. What are the systems that is supporting the business, what those systems are doing, and how they help create the overall architecture. Last but not least you will understand the dependency between these systems and how each system interacts with each other.

This context map should ideally be kept up to date and evolved over time. This is extremely useful for future decision making and allocation of capital. For CTOs and Chief Architects, this is the starting point to any strategy you put forward to evolve your business. If you don't have a context map you are shooting in the dark and your decisions are more likely to be wrong. The success of your strategy depends on how well you make sense of the current architecture of your enterprise.

Dhanush Hetti