Research and investigation inside a big legacy project is always a challenge and pain point. Architecture assessment is one of the Architect’ 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 more in a week and bring real value for the client?
Most architects and technical leaders facing so activity as architecture assessment. It could be a semi-formal process or separate service as it is in our company, nevertheless, probably most of you dealt with this.
Our approach
I will tell how it is in our company and how I deal with this, but the approach is the same and you can easily adjust it according to 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 thinks that everything is great and it is very suspicious. We had these cases and in reality, they had a bunch of issues.
- 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. I faced only one case when the client requested the assessment. This case – everything is bad, very bad. Usually, the client understands that there are some global issues with the project, but could not find the root cause and decompose this.
External assessment is a more complex case. The review should be more formal. Projects are big and outdated. There are a lot of issues, problems, and bugs. The assessment report should be done in a couple of weeks and contains major issues and recommendations for improvements. If you handle an external assessment, internal will be a piece of cake.
Enterprise architecture assessment
A typical project for assessment – it is a big, legacy, enterprise project with a number of issues. Clients go to us and ask to fix issues. It is like an iceberg, the client sees the only top of issues.
What problems client articulates and knows:
- Performance issues
- Usability problems
- Long 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
It is a strict flow, you can adjust it depending on your company and project.
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 – .Net, Java, Python, and other technical leaders depending on project 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:
- Questionary 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 deployment. If it is a cloud. Should to know what cloud services are using? 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 repository and documentation on how to build.
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 observing 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 how is real inside.
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 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 on all levels. 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. This time 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 autogenerated 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 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. How to show business value from architecture refactoring, we have already discussed.
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.
As the outcome of your meeting send 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.
Based on my experience many assessments were finished in the middle of improvements or never started improvements at all.
Your goal to highlight client most valuable improvements – minimal cost and time, maximum technical value.
I wish you a clean code and good architecture.
