uapsh/arc42-template

A template for documenting IT architecture in git, using arc42, docsify and plantuml

Architecture document template

A template for documenting IT architecture.

Goal

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.

Prerequisites

• NPM (installer)
• graphviz (on Mac: brew install graphviz)
• plantuml (on Mac: brew install plantuml)

Recommended: VSCode with PlantUML extension.

Included tooling

• arc42 for the structure
• docsify to generate a website
  • Zoom plugin
  • Edit on GitHub plugin
  • Docsify to PDF
• plantuml for diagrams
• ADR (architectural decision records) for decisions
• remark-lint for linting markdown.

Getting started

• 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 install from the docs directory.
• Run npm run serve to view the docsify website.

How to use

To show the webpages in your browser, do npm run serve.

Text

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

Architecture decision

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.

Diagrams

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.

Export

To generate a PDF, do npm run pdf. It will be created in the output directory. See settings in .docsifytopdfrc.js.

Credits

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