This article will outline how to write an Architectural Review for a software system so that the client who has ordered the review is 100% satisfied. I have done several reviews for Oracle WebCenter, Oracle ADF and Oracle SOA Suite (incl. BPM) for big banks and retail. The work always consist of 50% communication and 50% technical.
When you are invited for an architectural review, the first most important thing is not technical, but
What the customer needs from you
Obviously there is either something wrong in the system or the company that has hired you wants to improve some parts of it. You need to find where to start from by talking with someone as senior as you can find (CTO, CIO, Product owners). Usually they will give you a lot of background information (e.g. when the project started, who delivered it, what did go wrong in it, what are the major problems/opportunities) and send you existing documentation. They will also tell you where they see the project going, where they want to invest in (e.g. Business Intelligence and Mobile) and if you think this can be integrated in the solution.
Then you can start with writing your document’s sections for “Project History”, “Background of Implementation” and “Future Features and Improvements”. Now it is time for some technical work or see
What are the software modules/layers and how are they structured
This one seems obvious, but is the hardest to execute as big project artifacts’ are always scattered around.You will also need to check differences in the environments and deployment units. Usually big projects might include many integrated units, web services coming from other systems, exposed APIs.
After reviewing this you put your “Architectural Overview”, “Project Separation and Source Organization”, “Environment Management”, “Deployment Architecture and Environments” and “Versions and Patch releases”. Some people might argue, but I always go deeper and
Check sources and find bad implementation practices
While some people will go for the overview, I would go and make a deep code inspection. This makes customers happy and show them you are involved and want to really improve their situation. Also adding examples will show you have spent enough time to check the details. Plus you will always find some bad practice especially with complex frameworks like Oracle ADF and Oracle SOA Suite. Write your “Implementation Overview” and “Coding” paragraphs and proceed to my favorite
Interview key users of the system
Find one really optimistic person and the biggest pessimist. Then ask them what they want to see improved and what is not working. Be sure to bring your notebook as there will be many many comments, I guarantee. Users are always happy that someone finally asks them what they think. Finally check the code and the production console for exceptions and document your findings.
Wrap up with the “Future Features and Improvements”, give your advice for improving the delivery process (e.g. Automatic tests, logging and monitoring).
Using this approach you make sure all your statements are bullet-proofed with real findings (e.g. source code or interviews references). This way whoever is reading your review can be sure you have done your job.
