Discovering Architecture

I recently started a new job, and as with any new job comes the task of getting up to speed on the architecture. This can be quite a daunting task at the best of times, especially when there are many teams and repositories to work with. The company I've started at is large, and the area I work in has seven teams and is looking to increase that, meaning there is a lot of ground to cover and no clear place on where to start. So I thought I'd put together some thoughts on how I usually go about this.

Meetings and which to attend

The short answer to this is all of them. Attend the standups, product discussions, planning meetings and any cross-team initiatives. You will be spending all your day in meetings, to begin with, but you will also be absorbing a lot of information. How teams work, what work is critical, and the plans for the coming months. All vital information. It'll also help you pick up on any acronyms, which can be one of the more frustrating parts of starting a new role.

Eventually, you'll start to learn which meetings are helpful and which are not and gradually begin to step away from them.

Interviewing colleagues

Speak to your line managers and find out who it would be helpful to speak with. Ask for people from product and software as both will be useful.

When it comes to software developers, you should ask for any existing architectural diagrams. It doesn't matter if they are old. Ask for any code repositories they are responsible for.

It would help if you also asked for a code walkthrough. Make sure to ask questions about the decisions and why they were made. Were they made because of time constraints or because of dependencies?

With product managers focus on learning the pathways and how people use the product. Pay attention to any complaints they have.

Start drawing

Drawing is the most crucial step.

I find the easiest way to get a better understanding of the overall architecture is to start drawing it out. It doesn't matter if the diagrams already exist. Creating the diagram yourself will help you absorb the information and clear things in your head, the same way writing enables you to revise for exams.

Below is the first diagram I've drawn. It's not yet complete, but it gives an idea.

Large green circles are internal services, and purple is external services. Small green circles are events, and green squares are HTTP calls.

Also, look to draw sequence diagrams and domain flow diagrams to map out the key processes.

Make sure to go back and interview people to get confirmation that your diagrams are correct.

First steps

It's important not to judge.

I often see people beginning somewhere new and looking at the codebase as legacy. It's not written in a style they are accustomed to. It contains peculiarities that don't make sense. There are often reasons why the code and architecture are like they are.

I like to start by looking for failure points in the architecture. I use the architecture diagram I drew to ask questions about what happens if any services go down. What are the technical mitigations for dealing with it, and what are the business. These things are often overlooked, especially in an application that has been running smoothly for a while.

I'll write these up in a table: failure, impact, technical mitigations, business mitigations.

I'll then present these back to the teams to get them to start thinking about these possibilities.