Architectural Overview

An Architectural Overview is a diagram or sketch that describes key architectural elements including: the shape of the system, architectural pattern usage, primary interfaces between subsystems and external systems combined with target deployment platform information, critical data schema and important service/component/class/module structure.

Just as we describe a mix of concerns and processes in the Big Picture we recommend creating a big picture view of an architecture that communicates its key concepts. We don’t recommend slavishly following a visual language such as UML, they are generally too restrictive. However, using common de facto symbology where possible is useful and standards like UML are a good source of common symbology. The purpose of an architectural overview is to explain the important structural, logical and physical characteristics of an architecture in a single diagram. In some user-centric pieces of work a User Experience Design may complement an Architectural Overview.

Key elements to include are:

  • a high level view of the structural pattern of the architecture (e.g. layers or pipes and filters etc.)
  • a breakdown of the most important contents of each major element (e.g. layer)
  • indications of target deployment infrastructure
  • key user/actor interaction
  • primary interfaces between subsystems and external systems
  • critical data schema

This is an anonymized overview diagram of a system:

This diagram is a lot richer than a traditional UML architecture diagram because it dispenses with many of the rules of UML, while keeping some of its useful symbology, and incorporates rich graphics to further explain elements. We haven’t even used color in this example, which can be used to significantly add clarity if done well.

Horizontally it describes a layered architecture (including target deployment infrastructure and client platforms) as well as user and system actors via a GUI and exposed APIs. Vertically it describes the dependency pattern between architectural layers, the main communication pathways through the architecture and an eagle eye view of its structural composition. We can see that all communication between layers is via exposed interfaces and that the framework layer is composed of two primary subsystems which also have exposed interfaces. The Data layer is managed by a proxy which delegates to a persistency controller and there’s an outline view of the data model.

The purpose of a diagram such as this is to provide a starting point to explain the architecture to someone else. We recommend using an architectural overview as the primary way of describing an architecture in a team and to interested stakeholders. For a very simple system there may not be much more needed in terms of architectural documentation however for most systems a number of mechanisms that describe the systems behavior will also be useful.

Integration Scenarios, provide an excellent way to describe an end-to-end thread through an architecture especially in a system-of-systems context. The graphical and textual techniques used in Integration Scenarios can also be used to describe architectural mechanisms.