Establish and Document the Application's Architecture and Design

This chapter explains how to establish and document an Application’s architecture and design, including the research and prototyping that shaped them.

What Architecture and Design Documentation Covers

Architecture and design documentation explains how the Application is structured and why. It typically covers:

• The Application’s context: its users, the Systems it interacts with, and its place within larger Systems.

• Its logical structure: its major components and how they interact.

• Its physical and deployment structure: how components are deployed across Instances, environments, and infrastructure.

• Its data design: the data it holds and how that data is structured and stored.

• Its interface and Integration design.

• Its security design.

• How the design addresses the key functional and non-functional requirements.

• Diagrams that make all of the above understandable at a glance.

Establish the Architecture and Design

Develop the architecture and design during the Design phase, building on the outcomes of any Research and Prototyping. Also document the research and prototyping work that influenced the Application, such as feasibility findings, technology evaluations, rejected approaches, and prototype results, because it explains why the design is what it is. Consider and record design alternatives, and use the enterprise’s architecture standards and reference architectures.

Document and Share the Architecture and Design

Record the architecture and design, with diagrams, in the Architecture and Design section of the Application Documentation, and record significant decisions as described in the chapter “Establish and Document the Application’s Architecture Decisions and Their Rationale.” Update the architecture and design with every Release that changes them, so that they always describe the Application as it currently is, not as it was first designed.

Best Practice: Establish and Document the Application’s Architecture and Design

It is a best practice to both establish and document the solution for how an Application is structured: develop its architecture and design deliberately, document them with clear diagrams and explanations, include the research and prototyping that shaped them, and keep them current with every Release.

Benefits: Current architecture and design documentation lets engineers change an Application safely, architects assess its fit with enterprise direction, and support teams understand what they are troubleshooting. Including the research and prototyping that shaped the design prevents future teams from repeating evaluations, or reintroducing approaches, that were already tried and rejected.

Connections to Related IF4IT Practices and Inventories

The Solutions Architecture Best Practices and Framework describes how solution architectures are created, documented, and reviewed. The Systems Development Lifecycle (SDLC) Best Practices describes the Research and Prototyping and Design phases.