A list of awesome ARCHITECTURE.md files
A good ARCHITECTURE.md file helps developers understand how and where to make changes, whether they are new to a project or not.
Diagrams, source code maps, and discussing invariants and design decisions is essential.
This can also be a dedicated section of your README.md files.
- Linux cryptography - Calls out different types of components, provides searchable areas, calls out invariants of different components, and describes structure with diagrams
- oh-my-zsh - Describes the initialization process, calls out environment requirements
- Flutter engine - Good use of high level diagrams to show the stack and it's parts. Describes the main processes. Describes platform invariants.
- VSCode - Good use of high-level diagrams. Describes source organisation.
- NextJS - Breaks architecture into separate files, calls out important dependencies.
- rust-analyser - Good diagrams, describes entry points and source organisation, discusses architecture considerations.
- Tauri - Well made source code map, discusses architecture considerations, calls out important dependencies.
- NeoVim - Describes the main processes/lifecycle
- GitLab - Calls out design decisions
- ESBuild - Great use of graphics for visualisations and project structure. Includes a list of important principles for the project.
- Redis - Good source code map. Overviews of key files. Good use of documentation comments in-code rather than inline comments.
- Matklad's take - ARCHITECTURE.md files are useful for >10k line project. They should be start with a bird's eye view, provide a high-level code map, and show high-level relationships. Call out searchable starting points, such as a project's entry point.
- John Jago's discussion - Explores esbuild & Redis' documentation. Users and contributors alike benefit from separating Architecture from a README. Using design principles, graphics, key files, and changelogs are important parts of good documentation.