Software architecture documentation

The software architecture documentation primarily serves these objectives:

• Enable fast and effective development
• Precisely plan the development project – times, resources
• To fulfill the regulatory requirements for the software architecture
• Facilitate the further development of the system and the training of new employees

Fast, effective, and plannable software development will succeed if the task (to develop software that meets the software requirements) is broken down into solvable subtasks, which can be distributed among many developers.

The prerequisite for this is a precise (documentation of the) software architecture, which is unfortunately neglected in many agile software development projects.

Regulatory requirements for software architecture documentation

IEC 62304 and the FDA require a documented software architecture, although the FDA’s requirements go beyond those of IEC 62304. The latter only requires a software architecture for software systems in safety classes B and C.

Note: Even if not required for class A by IEC 62304, the software architecture is considered being an activity of state-of-the-art software development and is required in the context of cybersecurity considerations (see IEC 81001-5-1)

Requirements of IEC 62304

If you want to document a software architecture and only want to fulfill the requirements of IEC 62304, there is not much to consider. The standard essentially only requires five things:

1. To identify software items
2. To describe interfaces between components
3. To identify SOUPs and describe their requirements
4. To classify components (default: class C)
5. To ensure traceability

FDA requirements

The FDA also requires a description or modeling of the dynamic behavior of the software architecture, usually modeled with sequence or activity diagrams. But here, too, the internal behavior of the software should be described, not the external behavior. This is one aspect of the software requirements.

Note that the FDA requires a software architecture for both ”documentation levels.” With the latest 2023 FDA guidances a software architecture needs always to be included in the submission.

Thoughts on the requirements for software architecture documentation

The regulatory requirements for software architecture documentation are only minimum requirements and not best practices: Describing software without considering the dynamic view might not be enough. A software architecture is successful if

• a programmer can develop the device from it without having to ask many questions (i.e., without having to make ad-hoc design decisions)
• and all requirements can be met with the device.

Please note: In a professional team, the real value is created when thinking and discussing (together), i.e., when designing the software architecture and not when coding!

However, an auditor will only check the quality of the software architecture documentation, not the quality of the software architecture itself.

Structure of the software architecture documentation

Outline

You can organize the software architecture document according to the following chapter structure:

1. Meta information (e.g., author, system, version, date, objective)
2. Executive summary
3. Context delimitation
4. Static view
5. Dynamic view
6. Deployment view
7. Cross-sectional aspects
8. Design decisions
9. Risk management and safety classification
10. Appendices

Note: ISO/IEC 42010 (helpful Wikipedia article) and the arc42 template are recommended as guidelines for “good” documentation of software architectures.

Static view

One of the most important chapters in the software architecture documentation is the static view, which describes the static or logical structure. From a regulatory perspective, you should describe at least the first two hierarchy levels of the software system, the blue and green “boxes” in the following illustration.

You have at least two options for structuring this chapter in the software architecture documentation:

Variant 1

1. subsystem A
   1. module A1
   2. module A2
   3. module A2
2. subsystem B
   1. module B1
   2. module B2
   3. module B3
3. subsystem C
   1. module C1
   2. module C2
   3. module C3
   4. module C4

Variant 2

1. building block level 1
   1. subsystem A (blackbox)
   2. subsystem B (blackbox)
   3. subsystem C (blackbox)
2. building block level 2
   1. subsystem A (whitebox)
      1. module A1 (Blackbox)
      2. module A2 (Blackbox)
      3. module A2 (Blackbox)
   2. subsystem B (whitebox)
      1. module B1 (blackbox)
      2. module B2 (blackbox)
      3. module B3 (blackbox)
   3. subsystem 3 (whitebox)
      1. module C1 (blackbox)
      2. module C2 (blackbox)
      3. module C3 (blackbox)
      4. module C4 (blackbox)

Scope of the software architecture documentation

Model “only” so precisely that you no longer have to make ad hoc design decisions. A short and precise document is better than an epic work that nobody reads and is no longer up to date.

40-50 pages is a good rule of thumb for the length of your software architecture documentation. You can achieve this if you work with images rather than extensive text.

If you want or must describe things in more detail, outsource the components/subsystem specifications into separate documents, for example. I particularly recommend this if you also use these subsystems or components in other software systems or devices.

Would you like support in documenting your software architecture quickly, precisely, and in compliance with standards so that you can develop maintainable software on time and within your budget? Our team will be happy to help!

Get in touch with us!