Architectural Review Framework

Streamlining Your Design Process

Software architecture is the backbone of any robust and scalable system. However, arriving at sound architectural decisions can often feel chaotic. Designs might be inconsistent, key stakeholders missed, and rationale lost over time. How can we bring structure, clarity, and efficiency to this critical process? Enter the Architectural Review Framework (ARF).

Think of an ARF as a structured approach, almost like an assembly line for design decisions. It's not about rigid bureaucracy but establishing a transparent, repeatable process for proposing, reviewing, and finalizing architecturally significant changes. Implementing an ARF signals the importance of planning and ensures that architectural work receives the focus it deserves.

Why Bother with an ARF?

Implementing an ARF brings tangible benefits:

• Consistency: Ensures architectural decisions follow a standard process.
• Clarity: Makes the rationale behind decisions explicit and discoverable.
• Collaboration: Provides clear points for stakeholder input and review.
• Risk Reduction: Helps catch potential issues early in the design phase.
• Knowledge Sharing: Creates a documented history of architectural evolution.

The ARF Workflow: From Idea to Decision

A well-defined workflow is the heart of the ARF. It guides a proposed change through the necessary stages of refinement and approval:

Collect Requirements: The process begins by clearly defining the problem and the proposed solution. Crucially, this step focuses on identifying architecturally significant changes – those impacting core structures, cross-cutting concerns, or key non-functional requirements.

Initial Scope Review: Conduct an initial review before deep diving to understand the scope. This review aims to decide on the type of design and identify who should be involved.

You will need to determine the type of design documentation needed. Is this a broader RFC (Request for Comments) seeking input on an idea, a formal AD (Architecture Decision) for a specific non-trivial implementation that proposes an elaborate system, or a more informal ADR (Architecture Decision Record) capturing a particular choice and its justification?

Identifying the Players: Who is impacted by the proposed change? Once we can answer that question, we can include the relevant teams in the feedback loop. The same person may serve multiple roles here.

• Participants: The engineers responsible for leading the change also author the design, respond to review feedback, and revise it if needed.
• Reviewers: Anyone who needs to be informed or might provide input. How difficult will the proposed change be to implement? Will it make application development easier or harder? What are the scalability and security ramifications? Assign specific individuals to analyze the proposal for technical soundness, feasibility, and alignment with standards.
• Decision Makers: The person or group ultimately responsible for approving or rejecting the proposal in its final form. If accepted, how will the change be funded in terms of staffing and time?
• The Guide: Chances are that you will need someone to help everyone else navigate the ARF process. Someone who has done this before and knows how to keep the process productive, rewarding, and on track. Typical titles for this person could be architect, staff engineer, lead programmer, or even manager.

Draft & Iterate: This is the core collaborative phase:

The participants create the initial proposal document, which should be either an RFC, an AD, or an ADR as decided during the initial scope review.

Designated reviewers provide feedback. Open discussions occur. These discussions often happen asynchronously via in-document comments but could also include in-person meetings, calls, or real-time chat. Let's explore what a healthy review process looks like.

For Participants:

• If someone posts a question about the design as a review comment. It's okay to resolve the confusion in the discussion. In the end, ask yourself this. Does the question indicate that the design isn't clear to someone skilled in the art? If yes, add the missing clarification to the design itself.
• It's natural to get in the habit of defending your design if someone posts a review comment that asks for a change. Before you do that, pause for a moment, take a breath, pretend you didn't author this design, and ask yourself this. Does the requested change improve the design? If it does, then make the change. Your job isn't to defend your design. Your job is to come up with the best design you can. The reviewers aren't attacking you. They are helping you do your job.

For Reviewers:

• Don't snipe. The name of the game is to improve the design, not elevate yourself at your colleague's expense.
• Be respectful. Not everyone has the same skill level. Reviews can serve as an excellent opportunity for mentoring.
• Ask yourself this one question before posting a comment that proposes a change. Is the primary motivation for the change based on the observation that you would have done the design differently? If so, then don't post the comment. Changes should be proposed for scalability, security, efficiency, maintainability, resilience, or correctness reasons and not due to personal preferences.

For the Guide:

• Be prepared to mentor, especially when drafting design specifications. Not everyone who knows how to code also knows how to design.
• You may also need to serve as the final arbiter during the initial scope review phase.
• If a discussion thread is starting to get too long and doesn't contribute much to answering why questions for posterity, then propose that the group move the discussion to a chat session.
• A healthy review sheds light on the subject but generates no heat. Be prepared to set boundaries if you notice any untoward emotional or psychological escalation.
• Look for signals suggesting a quid pro quo pattern in the review phase. Nothing undermines this process faster than an attenuated review due to an "I'll approve yours if you'll approve mine" agreement. Be prepared to interrupt this pattern with a corrective meeting.

The participants incorporate the feedback from reviewers and prepare revised versions. This cycle repeats until the proposal is either ready for a decision or abandoned.

Finalization: Once the review cycles are complete:

Incorporate the final changes based on the latest feedback.

The designated decision-makers make the formal decision (approve, reject, defer) and record that decision in the design. If the decision is to begin immediately with the implementation, follow your normal coding cycle which most probably starts with cutting tickets, assigning tasks, and getting estimates.

Design Document Formats

What should the actual documents themselves look like?

I recommend formatting the design document in markdown, which is well suited to the formatting needed in such documents using easy-to-remember ASCII art symbols. This text-based format is easy to review, revise, and track changes. More on this later.

Diagrams are essential in software architecture. Diagrams provide crucial information for communicating architecture in visual form. There are two flavors of diagramming formats to consider.

Text-based: Instead of drawing a diagram, you specify it as a graph with nodes, attributes, and relationships in an ASCII art sort of format. The software renders the actual diagram and makes all of the decisions about placement based on either its defaults or on some optional hints that you can specify.

WYSIWYG: (What You See Is What You Get) If ASCII art is not your cup of tea, you can draw the diagram using a more traditional drag-and-drop metaphor. You make all of the placement decisions yourself.

What should these diagrams look like? Here are two popular and effective models for communicating architectural information.

UML: Originally designed by James Rumbaugh, Ivar Jacobson, and Grady Booch, the Unified Modeling Language specifies seven types of structural diagrams (class, component, composite, deployment, object, package, profile) and seven types of behavioral diagrams (activity, communication, interaction, sequence, state, timing, use case). It can be very complicated, but most engineers learn UML at university.

C4: Named after the four types of diagrams (Context, Container, Component, Code), the C4 model is much more straightforward and more intuitive to read and comprehend by just about anyone.

Essential Tooling

While the process is key, the right tools can significantly streamline the workflow.

GitHub provides excellent support for the collaboration & version control of these designs. Use issues to collect ideas and requirements and to assign and track work to individuals. The participants can place the design document itself in a GitHub repository. Use Pull Requests (PRs) for the review cycle of the actual design documents. The GitHub PR process provides excellent diffing, commenting, and version history. Manage the ARF process using Projects by adding the relevant issues and PRs to the associated project.

The GitHub repository can be a repo designated for all designs for all engineering per division or team. Depending on the scope of the design, the document could be in a folder of the repo or mono repo that contains the code impacted by the proposed change.

Tools like Mermaid or PlantUML allow diagrams to be embedded directly in Markdown documents and version-controlled alongside the text. Tools like Lucidchart or Draw.io offer graphical interfaces for easily creating complex diagrams. However, you are responsible for keeping the WYSIWYG diagrams up-to-date, exporting them to PNG format, and committing all associated files to the repo.

Office Productivity & Communication: Standard Conferencing and real-time chat tools are vital for synchronous discussions when needed. Your organization already provides these tools, which are satisfactory for our purposes.

I discourage using office productivity tools to author and review design documents or diagrams. The GitHub PR does a much better job of CDC (Change Data Capture) for these design decisions, which will prove very useful later on when trying to remember the rationale of the decisions. Stakeholders who are not engineers may be new to the PR experience, but it won't take long for them to figure it out.

Data Analysis (Supporting Evidence): Sometimes, decisions need data backing. Spreadsheets or more advanced statistics tools (pandas or pyspark for Python, tidyverse in R) can help analyze metrics, performance data, or cost comparisons to justify choices. You can link directly to the spreadsheet or Jupyter Notebook from the design document. GitHub knows how to properly render both CSV and IPYNB files so commit your analysis to the repo in those formats.

Summary and Next Steps:

An Architectural Review Framework isn't about adding overhead; it's about investing in a smoother, more predictable, and higher-quality design process. Defining your workflow and leveraging the right tools can significantly improve your team's ability to tackle architectural challenges.

Need help designing or implementing an Architectural Review Framework tailored to your organization's needs? As an experienced software architect, I can help you establish best practices for effective and efficient design decision-making that is customized to your particular corporate culture.