Research and assessment inside a big legacy project is always a challenge and pain point. Architecture assessment is one of the architect’ consulting activities. Usually, we deal with huge old projects and should provide a result in a week or two.
How to assess projects with size 100k lines of code and even more in a week and bring real value for the client?
Most architects and technical leaders sooner or later will face with an architecture assessment. It could be a semi-formal process or separate service.
Kinds of Architecture Assessment
I will share my experience and you can adjust it based on your needs.
There are two types of architecture assessments.
Internal – we usually do it for our projects inside the company. A project can request an assessment for several reasons:
- The team considers that everything is great and it is very suspicious. Usually there are not ideal projects and every project has its own gaps.
- The team wants to validate the current solution and project.
- The team knows that they have issues. They can enumerate some issues and root causes, but want to get a full list of issues and recommendations.
External – this process more formal than an internal review. There are a couple reasons for external architecture assessment.
- Client acquiring another company and want to understand how big is technical debt and how much will cost refactoring and alignment to required architecture.
- Second reason for assessment is identification of the main project’s issues and providing a list of recommendations and improvements to achieve desired business and technical goals.
External assessment is a more complex case. The review should be more formal. Usually, projects are big and outdated. There are a lot of issues, problems, and bugs. Different specialists with different profiles could simultaneously assess a project to provide gaps in numerous areas like requirements, security, performance, test approaches and automation, continuous integration and continuous delivery, infrastructure, source code, architecture.
Enterprise Architecture Assessment
A typical project for assessment – it is a big, legacy, enterprise project with a number of issues. Clients could know partially about a project’s issues, but most issues covered under the water as a iceberg and most clients don’t aware about it.
What problems client articulates and knows:
- Performance issues
- Usability problems
- Long in time deployment
- Lack of unit and other tests
Issues unknown for a client, but probably present in a project:
- Security breaches
- Design problems
- Architecture issues
- Algorithmic mistakes
- Unsuitable technologies
- Technical debt
- Wrong development processes
Architecture Assessment Process
This flow is working for me and should work for you. Of course, you can adjust this approach for your own needs.
Request from Client
The client or delivery department initializes the request. A responsible person gets base information about the project and gathers needed experts. Depending on the project it could be different experts.
Solution Architect – the main person responsible for assessment and coordination.
Stack specific experts – for instance .Net, Java, Python, and other technical leaders depending on the project’s stack.
Cloud experts – it could be Azure, GCP or AWS cloud architect.
Infrastructure – DevOps, System administrator, etc.
Other experts: big data, machine learning, performance engineer, security expert, quality assurance.
Collect Project Information
You should get as much as possible information about the project. You can use different techniques depending on the situation:
- Questionnaire and other communication via mails. Less effective approach.
- Online meetings
- Sharing spaces like Google doc, Confluence, repositories, etc.
- On-site meetings. Most effective and expensive approach.
What do you need to get from the client?
High-level information. What is a project about? Domain and purpose of the project. Global goals and future targets. Main business drivers and strategies. Main issues and desired results.
Project-specific info. Technology stack, frameworks and programming languages. On-premise or cloud infrastructure. What cloud services, solutions and integrations are used? What architecture and design patterns are using?
Non-functional requirements. All requirements related to usability, performance, availability, security, portability, modifiability and so on.
Base use case and data flow.
Access to source code. The most important part! You should get access to the repository and documentation.
Access to infrastructure. Nice to have access to live environment dev/prod to investigate live systems. It is a great success if a client has an environment and performance monitoring tools. About these tools, we will talk in the next section.
Documentation. If a client has documentation it is a good start for assessment. It could be outdated and inaccurate, but it is a good start. Never trust documentation – validate it with the client and observe the real environment and source code.
Perform Assessment
How to handle so much information in the short term. First of all, parallelize efforts.
DevOps should evaluate infrastructure. The technical leader looks at code. A performance engineer investigates performance metrics. DBA (Database administrator) or data engineer should deep dive into data models.
But it is an ideal case when you have a lot of resources. Usually, assessment performs 1-3 persons. You can conduct assessment yourself having good knowledge in all these areas. In this case, you should automate all processes as much as possible.
Unfortunately, you have to read existing documentation manually. Having enough experience you can pretty quickly understand what is a quality of documentation. What is right and what is false. Sometimes you can see in documentation architecture that never will work in real life. It is a good point to think about what is actually inside the existing project.
Useful Tools to Automate the Evaluation
Code assessment is an easy exercise. You should use static code analyzers that show you design, performance and security issues. Here is a couple of them:
Structure 101 – It is a great architecture tool. It shows you a big picture, dependencies between modules. Cyclomatic and cross-dependencies. Potential places for refactoring and many others. Like all good tools, it costs good money, at the same time you can play with a 30 days trial.
SonarQube – good old tool. Code quality static analysis tool to detect code smells, bugs and security issues on 20+ programming languages.
All cloud providers have inside infrastructure monitoring tools. It helps you evaluate the cost and performance efficiency of VM, database instances and other cloud services. For AWS it is trusted advisor. For Azure it is just Azure Advisor.
Additional performance monitoring and logging tools can help you identify performance issues. Starting from a database and inefficient queries, backend code and frontend code as well. Even if the client doesn’t have these tools on the place you can pretty fast integrate these tools to production or stage infrastructure to detect performance issues.
As usually good tools have a good price. I would recommend a couple of paid tools. Of course, you could use open-source, but need more time for this. Nice to have integrated and prepared it in advance, not on the architecture assessment phase.
For security and penetration testing, there are a lot of tools. I would recommend the open-source tool for a security scan.
OWASP ZAP – web application security scanner.
Let’s shape all the data together.
Prepare Report
Start your report from the collected data. Describe all project’s business goals, constraints, use cases, non-functional requirements. After that should mention all input data like source code, documentation, infrastructure, and environments.
The next chapter put you findings based on automated tools and your manual investigation. Big auto generated reports put to an appendix. This section should be short main proofs of existing issues.
Categorize finding issues by severity like error, warning, info. You can choose your own grade, but it is common.
As an architect, you must provide recommendations to fix finding issues. Describe improvements and business values that will get a client.
Prepare roadmap with small iterations. Each iteration should have estimates, descriptions, and resources count needed for improvement, business, and technical values.
Deliver Report and Finalize Architecture Assessment
Never just send a report to the client via email. You should schedule a meeting with the client and tell about finding issues and emphasis on the most critical. Should mention items that the client never knows. Like security issues and how they could affect business. Propose your roadmap for improvements and discuss options most suitable for the client. It could be time, scope, resources.
These books about software architecture should help you design quality architecture documentation.
As the outcome of your meeting, send an architecture assessment report document.
Summary
Architecture assessment is a complex and hard activity. To conduct assessment successfully you need practice and professional skills.
It is real to get valuable results after one week of assessment even if you evaluate a big project yourself.
Your goal to highlight the client’s most valuable improvements – minimal cost and time, maximum technical value.
I wish you a clean code and good architecture.
