Ask HN: Are there any openly available software architecture documents?

AWS has nice whitepapers on their software architecture.

https://aws.amazon.com/whitepapers/?whitepapers-main.sort-by...

The book `Documenting Software Architectures ...` [1] can help.

[2] and [3] list a few example documents for Software Architectures, you can google further and find some more.

I think reading through a few sample documents and based on the expectations at your current job, you can derive the necessary doc.

[1] https://www.amazon.com/Documenting-Software-Architectures-Be...

[2] https://projects.cecs.pdx.edu/attachments/download/3146/Soft...

[3] https://www.voa.va.gov/DocumentView.aspx?DocumentID=188

C4 is pretty easy to learn, Arc42 has some sample documents that are very useful. They complement each other.

https://c4model.com/

https://arc42.org/documentation/

PRINCE 2 documents also come with a 'decision log', if you want something in a formal template.

PlantUML is useful for diagramming anything from sequences to system architecture to state machines. It's also widely supported in many modern text editors like emacs and VSCode. PlantUML components for AWS are widely available [1]. You may find RealWorldPlantUML a good place to start looking for examples [2].

[1] https://github.com/milo-minderbinder/AWS-PlantUML [2] https://real-world-plantuml.com/

Yikes, if you haven't been doing this as you go you've severely messed it up.

Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process

If you only have a few weeks then there might not be any good results: you have to spend time learning the framework and also provide the relevant/ required info.

It is an opportunity to learn and apply it forward to your new job.

I would also look at "The Architecture Of Open Source Applications", although it might be more detail than you're looking for.

Archi software to draw Archimate diagrams.

There is the excellent Architecture of Open Source Applications book, which is available online for free at http://aosabook.org/en/index.html

It contains architecture overviews of many open source projects.

I agonized over the best way to do this stuff for a while also and the best framework I've used so far is the C4 model (as mentioned elsewhere).

For documenting decisions on architecture this should be done as you go really but better late than never :). Using adr ( architecture decision records ) text / md files would be my approach. They will typically be kept alongside the code and source controlled

This might initially look to be be a little too specific for military / aerospace, but it can act as a good guideline for a table of contents and examples of what might go in each section.

https://github.com/VCTLabs/MIL-STD-498/raw/master/MIL-STD-49...

The US Military came up with their own standard for systems and software development (MIL-STD-498), which as evolved into IEEE and ISO standards. The nice thing about the US Military's standards is that they came with Data Item Descriptions (DIDs) that specify exactly what goes in each document.

Plantuml for drawing pictures together with the C4 Plantuml Plugin is helpful. i.e. you make high level overviews of your architecture and then „zoom in“

For decisions a table with some explainatory comments why you have decided to use this one thing and which alternatives you have considered and why those did not make it, helps. You can look up ADRs. (Decision Records)

Our design decision documents have essentially four sections: Problem description, solution options, comparison of the options, and decision. I find it helpful to clearly distinguish what is part of the problem and what part of the solution. The size of the sections varies a lot.

Meta information could be: Status, stakeholders, decision-makers, and rollout description. It also often has links to meeting protocols and tickets.

There are dozens at the Architecture of Open Source Applications ebook/site: http://aosabook.org/en/index.html

As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.

I've found this to be a pretty great resource: https://github.com/joelparkerhenderson/architecture_decision...

ADR is made for this

https://github.com/joelparkerhenderson/architecture_decision...

There are multiple variants. Simple or detailed.

Most important thing to convey is the conceptual framework used and assumptions made to simplify things. e.g. "We will fix problems only by altering the base image, not the build system." "We will not change to 64-bit build as a part of this change." The sort of thing so that if someone really internalizes the perspective, they will be able to decide all the details on their own. Also a basic picture is always very popular. The details should be in git someway or another, but being able to use the details quickly is the job of the overview. I find it useful to document common change workflows ('To add another type of processor, add the class name to this map in this file, provide a jar implementing that class here, and add a new ID to the enum here.')

GitLab has all of their docs online..I guess you can dig into them for inspiration

There are bunch of them, really.

But for general structure, using your end-user's user experience path (from start to end) as a guide and avoiding buzzwords as much as you can usually help. Think of Stripe's documentation, you want something as easily digestible as that.

- Software Design Patterns: https://en.wikipedia.org/wiki/Software_design_pattern

- Azure Application Architecture Guide: https://docs.microsoft.com/en-us/azure/architecture/guide/

- Azure Cloud Design Patterns: https://docs.microsoft.com/en-us/azure/architecture/patterns...

- Azure Architecture Framework: https://docs.microsoft.com/en-us/azure/architecture/framewor...

- Azure Cloud Adoption Framework: https://docs.microsoft.com/en-us/azure/cloud-adoption-framew...

- Cloud Computing Patterns: https://www.cloudcomputingpatterns.org/

- Microservice Architecture Patterns: https://microservices.io/patterns/index.html

- Amazon's Builders Library: https://aws.amazon.com/builders-library/

I found the 4+1 architecture docs very helpful when working with a recent client. https://en.m.wikipedia.org/wiki/4%2B1_architectural_view_mod.... What I like about it is that it separates the architecture into four views each for a different audience

import: English

import: Diagram

ok: Community

see: https://www.drupal.org/project/project_module?f%5B2%5D=im_vi...

Making use of colors in architectural diagrams really add depth to the information. Often applications involve internal and external (out of scope) components. Using common colors for each group of components really helps in the readability.

Tell them the code is so good it documents itself.