
Ask HN: Are there any openly available software architecture documents? - passenger
I&#x27;m about to leave my job for another and i&#x27;m tasked with documenting the existing architecture and flow of the app.<p>I&#x27;d also have to document why certain decisions were taken.
I&#x27;m looking for any openly available similar documents for guidance mostly around how to structure the document.
======
davalapar
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](https://en.wikipedia.org/wiki/Software_design_pattern)

\- Azure Application Architecture Guide: [https://docs.microsoft.com/en-
us/azure/architecture/guide/](https://docs.microsoft.com/en-
us/azure/architecture/guide/)

\- Azure Cloud Design Patterns: [https://docs.microsoft.com/en-
us/azure/architecture/patterns...](https://docs.microsoft.com/en-
us/azure/architecture/patterns/)

\- Azure Architecture Framework: [https://docs.microsoft.com/en-
us/azure/architecture/framewor...](https://docs.microsoft.com/en-
us/azure/architecture/framework/)

\- Azure Cloud Adoption Framework: [https://docs.microsoft.com/en-
us/azure/cloud-adoption-framew...](https://docs.microsoft.com/en-
us/azure/cloud-adoption-framework/)

\- Cloud Computing Patterns:
[https://www.cloudcomputingpatterns.org/](https://www.cloudcomputingpatterns.org/)

\- Microservice Architecture Patterns:
[https://microservices.io/patterns/index.html](https://microservices.io/patterns/index.html)

\- Amazon's Builders Library: [https://aws.amazon.com/builders-
library/](https://aws.amazon.com/builders-library/)

~~~
ignoramous
Apache Kafka's documentation is pretty good, too:
[https://kafka.apache.org/0102/documentation.html](https://kafka.apache.org/0102/documentation.html)

Also, for a 10,000 foot overview of popular open-source tools, see
[https://aosabook.org](https://aosabook.org)

------
claudiulodro
There are dozens at the Architecture of Open Source Applications ebook/site:
[http://aosabook.org/en/index.html](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.

~~~
cheez
The best book/pair of books about software that I have ever read.

Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.

~~~
ahartmetz
Effective C++ is mostly just a book about C++ pitfalls to avoid. It says
nothing about high level concepts.

------
Ididntdothis
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

~~~
billfruit
But then it is all .. vague. I do hope something better than can be done..
hand drawn diagrams can't represent details at different levels of magnitude,
like for example why statecharts are very expressive compared to other
diagrams is it's ability to have arbitrary levels of nesting, which is not
possible with handdrawn or even printed diagrams.

I feel like resorting to simple hand drawn diagrams, is in a way declaring
failure on being able to describe complex software requirements and structure/
behavior in a systematic graphical manner.

~~~
throw_14JAS
What works for me is to do things by hand, until all the possible information
I might want to share is present. I call it my inventory.

Then work on refining, editing, deleting, modifying.

Separate the creation from the editing/communication.

~~~
beamatronic
This x1000

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

[https://c4model.com/](https://c4model.com/)

[https://arc42.org/documentation/](https://arc42.org/documentation/)

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

------
deepaksurti
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...](https://www.amazon.com/Documenting-Software-Architectures-Beyond-
Engineering-ebook/dp/B0046XS3RO)

[2]
[https://projects.cecs.pdx.edu/attachments/download/3146/Soft...](https://projects.cecs.pdx.edu/attachments/download/3146/Software_Architecture_Document.docx)

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

------
zeko1195
AWS has nice whitepapers on their software architecture.

[https://aws.amazon.com/whitepapers/?whitepapers-main.sort-
by...](https://aws.amazon.com/whitepapers/?whitepapers-main.sort-
by=item.additionalFields.sortDate&whitepapers-main.sort-order=desc)

------
doctor_eval
I’m a huge fan of code as design [1], so I tend to do my architecture thinking
at a high level - the objects and interactions between systems - and then
write clear and simple code which expresses my intention. To this end, if the
code is clear then it doesn’t need to be documented heavily.

I’m also a big fan of DDD [2] and use his “box and line” drawings all the
time. There are loads of resources for DDD but I’ve linked to the book, which
is awesome. DDD has great concepts like Context Boundaries and Ubiquitous
Language which may simplify the documentation process.

It’s easy to think of architecture too abstractly or in terms of frameworks or
other complexifying concepts, but simple is good, and that’s true from top to
bottom.

[1]
[http://www.developerdotstar.com/mag/articles/reeves_design_m...](http://www.developerdotstar.com/mag/articles/reeves_design_main.html)

[2]
[https://www.goodreads.com/book/show/179133.Domain_Driven_Des...](https://www.goodreads.com/book/show/179133.Domain_Driven_Design)

~~~
j1elo
These slides do a good job at highlighting the important points from the DDD
methodology:

[https://www.cs.colorado.edu/~kena/classes/5448/f12/presentat...](https://www.cs.colorado.edu/~kena/classes/5448/f12/presentation-
materials/roads.pdf)

------
EliRivers
_I 'd also have to document why certain decisions were taken._

Yes please. So much this. With evidence, please, so that the decisions can be
revisited in the future and changed when they no longer apply. Every day I
open another source file on a system that was built over a decade by a
rotating cast of mostly first job software engineers without adequate
mentorship and (I wish I was making this up) having their C++ code reviewed by
a C programmer who gave them comments such as "just turn all these functions
into one-line macros", and someone who appeared to be mainlining late-nineties
OOP hype like it was going out of fashion and needed to get it all on the page
before someone beat him to death with an old Vic 20.

Every day we stare at it and ask ourselves why. Why was it done like this? Was
there a good reason back then? Does that reason still exist? If I rewrite it
to remove all this horror, will something else break? Even, oh God, even "What
is this actually _meant_ to do?" I can see what it _does_ do. What it does do
makes no sense. Did it ever make sense?

Even the occasional comment like "cheeky hack for performance" is often more
hindrance than help when a quick test shows it actually makes performance
worse. Did it _ever_ improve things? Did the hardware change underneath it
such that it no longer helps? Did other code change such that it no longer
applies?

Anyway, where this was going is that a decision recorded without evidence or
even the factors considered might as well have been a coin toss to the
software archaeologist having to maintain it in a decade's time. If the
decisions and reasoning aren't recorded, you're forcing someone to attempt to
reverse-engineer your state of mind, and that's an expensive and impossible
job.

------
weitzj
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)

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

It contains architecture overviews of many open source projects.

------
qznc
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.

~~~
crocal
These are not architecture documents but change management documents. Roll out
of such decisions should, among other things, result in an update to
architecture docs.

------
kejaed
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...](https://github.com/VCTLabs/MIL-STD-498/raw/master/MIL-
STD-498-templates-pdf/SDD-DID.pdf)

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.

------
mindcrime
I am a fan of Phillipe Krutchen's[1] "4+1" model[2], or variants thereof. The
book _Software Systems Architecture: Working With Stakeholders Using
Viewpoints and Perspectives_ [3] by Eoin Woods and Nick Rozanski is a really
good overview of the overall mechanism.

Also, while this bit is probably overkill for your current situation, you may
find value down the road in looking at some of the various "architecture
frameworks"[4] and reference models that are out there. Things like TOGAF[5],
DODAF[6], MODAF[7], TRAK[8], etc.

In any case, always remember the words of the immortal Bruce Lee:

 _“Absorb what is useful, discard what is useless and add what is specifically
your own”._

[1]:
[https://en.wikipedia.org/wiki/Philippe_Kruchten](https://en.wikipedia.org/wiki/Philippe_Kruchten)

[2]:
[https://en.wikipedia.org/wiki/4%2B1_architectural_view_model](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model)

[3]: [https://www.amazon.com/Software-Systems-Architecture-
Stakeho...](https://www.amazon.com/Software-Systems-Architecture-Stakeholders-
Perspectives/dp/0321112296)

[4]:
[https://en.wikipedia.org/wiki/Enterprise_architecture_framew...](https://en.wikipedia.org/wiki/Enterprise_architecture_framework)

[5]:
[https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Fr...](https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Framework)

[6]:
[https://en.wikipedia.org/wiki/Department_of_Defense_Architec...](https://en.wikipedia.org/wiki/Department_of_Defense_Architecture_Framework)

[7]:
[https://en.wikipedia.org/wiki/MODAF](https://en.wikipedia.org/wiki/MODAF)

[8]: [https://en.wikipedia.org/wiki/TRAK](https://en.wikipedia.org/wiki/TRAK)

------
cgarvis
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...](https://en.m.wikipedia.org/wiki/4%2B1_architectural_view_model).
What I like about it is that it separates the architecture into four views
each for a different audience

------
lanstin
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.')

------
bvogelzang
I've found this to be a pretty great resource:
[https://github.com/joelparkerhenderson/architecture_decision...](https://github.com/joelparkerhenderson/architecture_decision_record)

------
NicoJuicy
ADR is made for this

[https://github.com/joelparkerhenderson/architecture_decision...](https://github.com/joelparkerhenderson/architecture_decision_record)

There are multiple variants. Simple or detailed.

~~~
lllr_finger
ADRs are great, and don't need to be overly formal or use tooling. We've been
hand-writing Markdown-based ADRs
([https://github.com/adr/madr](https://github.com/adr/madr)) checked in with
our code in a docs/adr directory.

You don't put every little decision in of course, but most projects have at
least 1-2 areas where even the people involved with the decision have a hard
time recollecting all the context for the decision.

The downside, at least for OP, is that they're usually something you capture
at the time the decision is made - not when you're leaving a project.

------
myrloc
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](https://github.com/milo-minderbinder/AWS-PlantUML) [2]
[https://real-world-plantuml.com/](https://real-world-plantuml.com/)

------
Geee
I've used the C4 model to draw an overall system architecture (container level
+ external systems). [https://c4model.com](https://c4model.com)

------
markmiro
I think it's worth looking at it like another product that you produce. I like
to imagine someone seeing my code for the first time and trying to make sense
of it.

Architecture: this is often documented with some kind of diagram. I personally
find them to be unhelpful.

Flow: I'm guessing people aren't familiar with your UI. The best way to
document would be to record a video, but that might be a little extra. I would
make a powerpoint doc with screenshots to show the common flows.

For me, it kinda looks like this:

\- Assume expertise in the individual technologies you've used

\- If you picked the tech, then write why you did, and link to resources to
learn more about it

\- Write down which general constraints I placed on myself that might not be
common. EX: naming patterns, cyclomatic complexity, using a functional
approach, or being more point-free in a language where it's not common,
choices around duplicate code

\- Make a nested list of the folder structure and describe what each folder is
for (even if it feels obvious), and describe how the different parts interact
with each other. The questions to answer are: what are the high-level
dependencies between dirs? Are there any cyclical dependencies?

\- Find the knots (especially complex parts of the codebase) and make sure
they're documented properly

------
nullandvoid
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

------
jankar
A little known, but powerful notation for description and documentation of
architecture of Information Processing Systems is FMC [http://www.fmc-
modeling.org/](http://www.fmc-modeling.org/) This site features a link to the
Apache Modeling Project where a now outdated version of httpd was documented
using this methodology.

~~~
jankar
Link to Apache Modeling Project: [http://www.fmc-
modeling.org/category/projects/apache/amp/Apa...](http://www.fmc-
modeling.org/category/projects/apache/amp/Apache_Modeling_Project.html)

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

------
bhamp0
Archi software to draw Archimate diagrams.

------
harshulpandav
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.

------
TruffleLabs
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.

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

~~~
Carl_Platt
Do you have a specific link one can start digging through?

------
luxuryballs
Tell them the code is so good it documents itself.

------
mitchtbaum
import: English

import: Diagram

ok: Community

see:
[https://www.drupal.org/project/project_module?f%5B2%5D=im_vi...](https://www.drupal.org/project/project_module?f%5B2%5D=im_vid_3%3A116)

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

