A template for documenting IT architecture.
Architecture documents should be easily:
- accessible
- searchable
- reusable
- versionable.
With git, you automatically get a detailed history and change log of any document. It aligns well with the way of working of the development team, and more and more that of operations (see GitOps, Infrastructure as Code, Configuration as Code). Maintaining everything in adjacent git repos ensures better versioning and visibility.
Recommended: VSCode with PlantUML extension.
- arc42 for the structure
- docsify to generate a website
- plantuml for diagrams
- ADR (architectural decision records) for decisions
- remark-lint for linting markdown.
- Fork or clone this repository.
- Change the name and description of your project in the
docs/package.json. - Add the name of your project and the git repository in
docs/index.html. - Optionally change the ADR template in
lib/adr_template.md. - Do
npm installfrom thedocsdirectory. - Run
npm run serveto view the docsify website.
To show the webpages in your browser, do npm run serve.
Just edit the contents of the files in the docs directory. Docsify does not need to rebuild anything to pick up the changes.
To lint, do npm run lint or, to check language, npm run lint-language
Add an ADR with npm run adr "Name of decision". Edit the file in the docs/adr directory.
Run npm run toc to update the Table of Contents.
Source and image outputs of diagrams are in docs/diagrams. Plantuml is ideal for simple visualizations
like sequence, class or deployment diagrams. A theme is included in the lib directory.
For system context diagrams and high level component models, C4 is a clean and lightweight way of communicating on the right level of depth. This repo includes an extension for plantuml.
After creating or updating diagram sources, run npm run diagrams to generate the png files.
To generate a PDF, do npm run pdf. It will be created in the output directory. See settings in .docsifytopdfrc.js.
© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.