Video available to subscribers only

Click here to see how you can get access.

Already have an account? Log in.

Software Architecture Documentation

Time to draw some diagrams and document some interfaces for CrowdCovid.

Let's draw some diagrams!

First, to avoid doing too much work, we briefly check what sort of software architecture documentation is needed for each (62304) software safety class. Spoiler: For class A, you need much less than for B and C.

We'll be doing three things:
  1. Create a software architecture diagram in draw.io.
  2. Create software interface documentation.
  3. Document the database schema.

We'll head over to draw.io to create a software architecture diagram of CrowdCovid. Remember, it's a Rails application which essentially runs in two places: The backend runs somewhere in the cloud while the frontend runs on the user's computer in their browser.

Then, we have to show the communication (and relation) of the backend instances to the postgres database and redis cache / message queue. We also need to take care of our static file hosting (e.g. AWS S3) and where to place it. All runtimes should be specified - so the Chrome V8 JavaScript VM for the frontend and MRI for the backend. We also need to include the push notifications somewhere in the diagram.

Next, we create the interface documentation. Luckily, the Rails app only has one REST endpoint which serves JSON, all other views are server-rendered (like in the nineties! good times.). We'll see how we can create "a poor man's swagger documentation" which conveys the relevant information without causing us too much pain.

Like with most (?) technical documentation, here it's especially important to focus on creating something that is useful to you and could e.g. be used for onboarding of new developers. Don't create regulatory documentation for its own sake.

Finally, we'll document the database schema.

And don't forget that your software architecture also needs to beĀ verified, e.g. by a review similar to that you've done for the software requirements.

Resources