Refining Architecture
Software architecture is not a static document, instead, it's a continuous iterative process throughout each increment. This guide serves as a reference for the roles providing and describing different levels of architecture.
Intended for
Anyone providing architecture e.g.:
- A system architect describing the system architecture roadmap through the system architecture vision.
- A system architect describing the system architecture with different related products.
- An architect describing the product architecture roadmap through the high-level plan for the product.
- An architect describing the product architecture or different components within the product.
- An architect describing the security architecture.
Overview
Not all requirements can be a source for architecture. Some requirements have a larger impact on the architecture of a system than others. Such requirements that impact the architecture can be referred to as architecturally significant requirements. These requirements are demanding to the performance, interoperability, usability, security, and availability of a system. Architects need to identify and refine these requirements for the architecture documentation.
System architecture typically has system epics as a source of input while product architecture typically has epics and features as input.
Artifacts produced from the architecture process are utilized across multiple functions in the development and release life cycle. A container-level architecture can be utilized to identify the respective development teams to design the interfaces across the containers. A component-level architecture can be utilized to develop the design within the component to achieve functionality. A deployment architecture can be utilized by the test group to prepare the setup. Similarly, artifacts like threat models can be utilized for security certifications.
Details
Note: These markdown templates for Architecture Descriptions can be copied and used when creating architecture pages.
Who provides input, and who receives the output?
The diagram and artifact table on the Architecture process page gives an idea of the relationships of the architecture process and the roles involved in the different artifacts.
System epics, epics, and features are inputs for architecture from the requirement process.
The architecture description describes the high-level design of the product and is an output to the software and hardware development processes. Its content is based on different visual interpretations of how the requirements shall be fulfilled, e.g. package, component, activity, sequence, and state, along with descriptions of the composition of the product and its dynamic behavior.
Which model to use?
Several well-known models can be used to refine and document architecture, e.g. UML and C4.
UML has been around for a long time and is a general-purpose modeling language. It contains several different diagram types that can be used to visualize the architecture.
C4 modeling can be used to describe the architecture. The C4 model focuses on "abstraction first", providing 4 levels of diagrams to explain the architecture.
In general, pick the model that offers the best visualization of the architecture without complicating the documentation process too much.
Which tools to use?
The primary tool must be the approved document management system (DMS) for archiving purposes. How the documents/artifacts are created can vary between projects and even teams.
Projects and teams are allowed to choose any tool based on their experience and the availability of the tool. A few recommendations are EA, Visio, draw.io, Visual Studio Code, and PlantUML.
- Visual Studio Code, with extensions:
- Plant UML. Plant UML diagramming extension that allows preview and diagram generation.
- Markdownlint. A tool that assists in checking markdown files and flag style issues.
- Code Spell Checker. Spell checker for source files.
- draw.io. A free diagram tool. The online tool is also available as a desktop app.
- Mermaid. To generate sequence diagrams, Gantt charts, and flowcharts on the fly in the Azure DevOps wiki.
- Enterprise Architect. A model-driven tool supporting UML, from Sparx Systems.
When do you start?
Architecture documentation shall start with system epic and evolve along with the epics and user stories. Thereafter it is continually refined. Architecture and documentation shall be ready one program increment ahead of implementation activities.
At which level? High-level architecture, software developer level? What hierarchy/structure to use?
Static and dynamic diagrams shall be available as outputs.
Three levels of architecture are described in the process pages: strategic, system, and product. Strategic primarily covers the system roadmap, (system architecture vision). The system level is the owner of the system (S+, xA, Heritage) architecture whilst the product level covers product architecture, security analysis, safety analysis, and software/hardware interfaces.
Where do you do it?
The architecture is stored in different locations depending on at what level you are going to document it.
The overall system architecture documents the vision and architectural roadmap.
The integration of the vision into the different systems is documented in the respective systems architecture.
Individual streams document the more detailed product and component architecture.
How to review (references, whom to include)?
When the architecture refinement is ready for review, follow the How-to Edit, Review, and Approve Markdown Files guide. The review viewpoints (RACI) are listed for different artifacts on the Architecture process page.