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:
- A high-level diagram of all your software systems
- 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
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:
- The actual runtimes in which code is executed. For mobile phones, that’ll be the Android and iOS runtimes. For the backend services, this is the JVM (GitHub link to backend repo). You could just draw boxes around the services in which you note the runtime.
- Where stuff is hosted and network isolation stuff. I suppose the backend(s) run on some cloud service. All of them? Is there some network-level configuration so that certain services are only reachable internally? You could also draw a few more boxes to show this.
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.
