Bridge the Gap: IEC 81001-5-1 and Architectural Documentation as Code

In the highly regulated world of healthcare IT, documentation is not just a “nice-to-have”—it is a legal and safety requirement. With the introduction of IEC 81001-5-1 (Health software and health IT systems safety, effectiveness and security — Part 5-1: Security — Activities in the product life cycle), the bar for architectural documentation has been raised significantly.

As healthcare architects, we are now required to maintain a continuous, versioned, and secure “Architectural View” of our systems throughout their entire lifecycle. But how do we bridge the gap between the agile, developer-centric world of Markdown and Git, and the corporate, compliance-centric world of Confluence and PDF audits?

The Challenge: Compliance at the Speed of Development

IEC 81001-5-1 mandates several key documentation activities:

1. Secure Architectural Design: Documenting security-by-design principles.
2. Threat Modeling and Risk Assessment: Maintaining a live record of identified threats.
3. Software Bill of Materials (SBOM): Keeping an up-to-date list of dependencies.
4. Accompanying Documentation: Providing clear security guidelines for operators and users.

Traditionally, this leads to “Documentation Drift,” where the architecture diagrams in Confluence are six months behind the actual code in production. This is a major compliance risk.

The Solution: Documentation as Code

I have developed a framework to solve this problem: the architecture-documentation project.

This project implements a Documentation as Code workflow that keeps your architectural artifacts close to your source code while ensuring they remain accessible to non-technical stakeholders.

Key Features of the Framework

• MkDocs Material: Provides a beautiful, searchable, and responsive documentation site that developers actually enjoy using.
• Confluence Bi-directional Sync: Use the cf-export and markdown-confluence tools to pull content from Confluence for editing in your favorite IDE, and push it back for stakeholders to review.
• Automation via Makefile: Simplify complex workflows with commands like make import, make serve, and make publish.
• PDF for Compliance Evidence: Instantly generate high-quality PDF snapshots of your entire architecture for audit submissions using make pdf.

Implementing IEC 81001-5-1 with the Framework

By treating your architecture as code, you directly address the requirements of IEC 81001-5-1:

1. Maintaining the Security Architecture View

Instead of static images, keep your architecture views in Diagrams as Code (like PlantUML or Mermaid) within your Markdown files. This ensures every change to the architecture is caught in a Git Commit, providing a perfect audit trail of design decisions.

2. Living Threat Models

Host your threat models and risk assessments directly in the docs/ folder. As new features are added, the threat model can be updated in the same Pull Request, ensuring that security is never an afterthought.

3. Bridging the “Collaboration Gap”

Compliance officers and medical directors often live in Confluence. By syncing your Git-managed docs back to Confluence automatically, you ensure that the “Source of Truth” is shared across the entire organization without forcing everyone to use Git.

4. Continuous Compliance Evidence

With the PDF export feature, you can automate the creation of “Compliance Artifacts” as part of your CI/CD pipeline. Every release can automatically package its own architectural documentation, signed and ready for the Quality Management System (QMS).

Getting Started

You can spin up your own documentation-as-code environment in minutes:

# Clone the repository
git clone https://github.com/gjergjsheldija/architecture-documentation.git
cd architecture-documentation

# Setup dependencies
make setup

# Import existing pages from Confluence
make import

# Preview locally
make serve

Conclusion

IEC 81001-5-1 shouldn’t be a burden; it should be an incentive to build better, more transparent systems. By adopting a Documentation as Code approach, we can move away from “Check-the-box” compliance and towards a culture where architectural security is integrated into every line of code we write.

Explore the project and contribute on GitHub: gjergjsheldija/architecture-documentation