Architecture.md

• go-concise-encoding

  8 30 6.9 Go

  Golang implementation of Concise Binary and Text Encoding

I've started doing this in my larger projects e.g. https://github.com/kstenerud/go-concise-encoding/blob/master...

An architecture document should be the code equivalent of a combined street map and tourist guide. Its purpose is to bring strangers up to a minimum level of familiarity with the code as quickly as possible. That includes where things are, why it was architected this way, things to look out for, and a few interesting points of weirdness perhaps.

• stenographer

  1 1,751 0.0 Go

  Discontinued Stenographer is a packet capture solution which aims to quickly spool all packets to disk, then provide simple, fast access to subsets of those packets. Discussion/announcements at [email protected]

  

I really like this DESIGN.md[1]. Might not be as code specific as what tfa is talking. I find design decisions really helpful when evaluating if a tool or solution is useful for my needs. Especially if it elaborates on priorities made in the project.

[1] https://github.com/google/stenographer/blob/master/DESIGN.md

• SurveyJS

  surveyjs.io sponsored

  Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.

  

• drawio-desktop

  125 46,687 8.6 JavaScript

  Official electron build of draw.io

  

I've started using draw.io [1] for diagrams I want to embed in markdown files. The cool feature about draw.io is that it can embed the data structure describing the diagram in a png file. So you get a PNG file that is both source code for your diagram (so you can edit it later), as well as the presentation (you can embed png files and they will render fine in Github hosted md files).

Then I use the markdown-images package [2] for Sublime Text, and I can see those png images in my markdown files in the editor as well.

Benefits of this approach:

* Powerful diagram editor, free to use.

* Editable diagram and embedable image in one file.

* Diagrams rendered in text editor.

[1] https://github.com/jgraph/drawio-desktop

• Demo

  1 5 0.0

One of the things I added to my diagramming tool recently was the ability to sync with a Github repo. So whenever you make changes to this architecture, it'll push changes to the repo, with screenshots directly in the README (turning the repo into a diagram presentation).

This also allows people to colocate the diagrams alongside the code by including the synced repo as a submodule.

https://github.com/terrastruct-bot/Demo

• diem

  15 16,697 5.9 Rust

  Diem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.

  

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md, but it's even more dope to be able to click through it and have submaps of how other components are structured.

Displaying the folder/file structure and explaining what is what is a must. For example: https://github.com/diem/diem/tree/master/consensus#how-is-th...

• Joplin

  771 42,770 9.9 TypeScript

  Joplin - the secure note taking and to-do app with synchronisation capabilities for Windows, macOS, Linux, Android and iOS.

For my app I've started putting architecture related documents under /spec [0]. I feel documenting every aspect of the architecture is hard and time consuming, it also needs to be kept up to date. However it's worth documenting at least the trickier parts of the app.

[0] https://github.com/laurent22/joplin/tree/dev/readme/spec

• rust-analyzer

  207 9,320 10.0 Rust

  Discontinued A Rust compiler front-end for IDEs [Moved to: https://github.com/rust-lang/rust-analyzer] (by rust-analyzer)

  

We have something similar in https://github.com/rust-analyzer/rust-analyzer/blob/master/d....

An interesting systemsy difference is that missing style.md means more work for maintainers (as they need to do more cleanup), while missing architecture.md means more work for contributors.

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

• cl-test-grid

  3 82 1.9 NewLisp

  Collaborative testing of Common Lisp libraries

  

I also use such hierarchical style, with lower level REAODMEs refferring iddividual source files. So that user continues from READMEs to code comments.

Example: https://github.com/cl-test-grid/cl-test-grid#system-architec...

• share-file-systems

  34 122 8.7 TypeScript

  Use a Windows/OSX like GUI in the browser to share files cross OS privately. No cloud, no server, no third party.

https://github.com/prettydiff/share-file-systems

• Redis

  318 64,821 9.7 C

  Redis is an in-memory database that persists on disk. The data model is key-value, but many different kind of values are supported: Strings, Lists, Sets, Sorted Sets, Hashes, Streams, HyperLogLogs, Bitmaps.

  

100% agree. A very good implementation of your ideas can be found in the Redis codebase. Most important files have a long doc comment in the beginning.

See https://github.com/redis/redis/blob/unstable/src/ziplist.c for an example.

• Outline

  194 24,001 9.9 TypeScript

  The fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.

  

Thanks for the prompt – we had a rough version of this at Outline in the README but I've gone ahead and pulled it into it's own document with a pointer from the README and fleshed out the docs:

https://github.com/outline/outline/blob/main/ARCHITECTURE.md

Suggest a related project