Hiring or looking for a job in Digital Health? Check out our Digital Health Jobs board

Articles Technical Documentation

Updated May 24, 2023

Medical Device Software Architecture Documentation (IEC 62304)

Dr. Oliver Eidel

The IEC 62304 requires you to document your Software Architecture. As always, the standard doesn’t provide many details on how you should actually do that. This is good and bad: You can do it however you like, but nobody’s going to tell you how to do it.

Most people then get lost because they have no indication on which level to document things.

Here’s how I would do it. Roughly speaking, at the minimum you should have two things:

  1. A high-level diagram of all your software systems
  2. Interface documentation for each software system

Let’s look at some examples. This diagram is taken from the documentation repo of the German Covid Tracking App “Corona-Warn”:

High-level Software Systems Diagram

Corona-Warn Backend High-level Diagram

It’s part of a pdf which describes the architecture of the backend. This is only one of many figures - it’s the most high-level one.

It shows which software systems (another 62304 term) exist and how they communicate with each other. There’s the “Corona-Warn App” (yellow box) which runs on a mobile phone (gray box). It communicates with the Verification Server and Corona-Warn-App Server (blue boxes). And then there’s a Content Delivery Network (CDN) somewhere, and of course the app connects to other phones via Bluetooth to do contact tracing. You get the idea.

I’d add a few things to this diagram:

Get the idea? Now, which tool should you use? I suggest draw.io or Lucidchart. But really, this is just about drawing a few boxes. Choose whatever gets the job done for you.

A common question now is: Should you manually update this diagram every time you change your software architecture? Or should you attempt to automate it? Short answer: Draw it manually. Read my answer here.

Interface Documentation

The second part of your software architecture documentation should be documenting your interfaces. Those could be REST endpoints of your backend (or GraphQL if you’re fancy) or class / instance methods in object-oriented programming languages. I wouldn’t document all of them, only those which are exposed publicly and used by other services.

So, in the Corona-Warn example above, you could document the endpoints of the Verification Server and the Corona-Warn-App Server. Any time there’s a box in a systems diagram which offers public methods / endpoints, I’d document those.

This is obviously a trade-off between regulatory requirements and usefulness. Should you document all your interfaces and methods instead? It depends.

Try to view this from an angle of “What could be useful for us?”. Specifically, what would be useful for your if you’d be onboarding a new software engineer?

Having a high-level systems diagram would be quite helpful for them to get an overview. Public interface documentation would also be great if they should communicate with one of your services.

And the good news is: It’s often easy to auto-generate interface documentation (with Swagger UI etc.). So it’s an easy win.

Final Thoughts: Write Code First?

The actual goal of the 62304 seems to be that teams think about a software architecture before writing code. I think that generally makes sense, at least on a high level. Unfortunately, most startups have never worked this way and prefer to write code and come up with architecture thoughts along the way. This leads to things being done in the wrong order: Code gets written first and then architecture gets documented based on that code.

You may get away with this for the first iteration of your product, prior to your first certification. But once you’ve got a certified medical device on the market, you’d rather have processes in place to evaluate changes to the architecture before implementing them.

This applies to high-level systems diagrams. While the 62304 includes interface documentation as part of the software architecture documentation, I wouldn’t go that far. Which developers ever knows the methods they plan to write prior to implementation? It’s useful to have it documented, but I wouldn’t attempt to write it down before you’ve actually written some code. And then it can be auto-generated anyway.

On a slighty different note: You want to get your medical software certified under MDR but don't know where to start? No worries! That's why we built the Wizard. It's a self-guided video course which helps you create your documentation yourself. No prior knowledge required. You should check it out.

Or, if you're looking for the most awesome (in our opinion) eQMS software to manage your documentation, look no further. We've built Formwork, and it even has a free version!

If you're looking for human help, did you know that we also provide some limited consulting? It's limited because we are not many people. We guide startups from start to finish in their medical device compliance.

Congratulations! You read this far.

Get notified when we post something new.

Sign up for our free newsletter.

Dr. Oliver Eidel

I'm a medical doctor, software engineer and regulatory dude. I'm also the founder of OpenRegulatory.

Through OpenRegulatory, I've helped 100+ companies with their medical device compliance. While it's also my job that we stay profitable, I try to dedicate a lot of my time towards writing free content like our articles and templates. Maybe that will make consulting unnecessary some day? :)

If you're still lost and have further questions, reach out any time!


If you have any questions or would like to share your opinion publicly, feel free to comment below. If you'd like to reach out privately, send us a message.

No QMS on this planet will save you from creating crappy software.