Architectural review

What an architectural review covers and what to prepare before requesting one

An architectural review of code typically includes an assessment of the overall design and structure of the codebase, as well as its adherence to established architectural principles and patterns. Specific areas that may be reviewed include:

• Code organization: The review will assess how the codebase is organized, such as the structure of the file and folder hierarchy, the naming conventions used, and the use of appropriate abstractions and design patterns.

• Performance: The review will assess how well the codebase is optimized for performance, such as the use of appropriate data structures and algorithms, and the avoidance of performance bottlenecks.

• Scalability: The review will assess how well the codebase is designed to scale and handle increased load, such as the use of appropriate caching and indexing strategies, and the ability to handle a large number of concurrent requests.

• Security: The review will assess the security of the codebase, such as the use of appropriate encryption and authentication methods, the handling of sensitive data, and the avoidance of common security vulnerabilities.

• Maintainability: The review will assess how easy the codebase is to maintain, such as the use of appropriate documentation and comments, the use of consistent coding conventions, and the ease of locating and modifying code.

• Testing: The review will assess the quality of the automated tests that are present in the codebase, such as the coverage of tests, the use of appropriate testing frameworks, and the quality of test assertions.

• Modularity and reusability: The review will assess how well the codebase is designed to be modular and reusable, such as the use of appropriate interfaces, the separation of concerns, and the ease of integration with other systems.

• Compliance: The review will assess how well the codebase adheres to relevant standards, regulations and best practices.

• Technical debt: The review will assess the technical debt of the codebase, such as the presence of legacy code, the use of deprecated libraries and technologies, and the need for refactoring.

Preparing for an architectural review

Before an architectural review, it is important to have written documentation of the codebase that can be used as a reference during the review.

This documentation should include:

• A high-level overview of the module’s intended functionality.
• A high-level overview of the module’s architecture. This should include a diagram of the module’s classes and their relationships to each other. It should also include a diagram of the module’s data flow.
• A list of any direct dependencies that the module will have (e.g. Composer or npm packages).
• A list of any other modules that the module will depend on or interact with, if any.
• A list of any plugins that the module will be used in (e.g. Bluehost plugin, HostGator plugin, etc).
• A list of any expected data dependencies. For example, is certain data from the hosting platform, WordPress, or another module expected to be present? If so, what data is required and how will it be used? What happens if the data isn’t there?
• A list of any data that will be stored by the module. What is the data needed for and how will it be stored? Will the data be cached? If so, how long will it be cached for?
• A list of any APIs that will be consumed or provided by the module. Provide the API endpoint names and URLs. What are the expected inputs and outputs? Will the responses be cached? If so, how long will they be cached for?
• A list of any expected security considerations.
• A list of any expected performance considerations.
• A list of any expected privacy considerations.
• A list of any expected accessibility considerations.
• A list of any expected internationalization considerations.
• A list of any events that will be sent to the Hiive.

Related

• Code review and release restrictions

  Who reviews what, who is allowed to release, and the bar a PR must clear to merge

• Module development

  What module owners are responsible for, and the flow from feature branch to plugin PR