Software Architecture Documentation with arc42 and C4 Model

This repository provides an example of generating architecture documentation using the arc42 template and the C4 model, with the help of Structurizr CLI and Asciidoctor. The documentation includes various architectural views and diagrams, generated automatically using Docker and Docker Compose locally, or by using GitHub pages or Confluence.

The complete process is explained in details in the text.

Give a Star! ⭐

If you like or are using this project to learn or start your solution, please give it a star. Thanks!

Overview

The repository demonstrates how to:

1. Define architecture using Structurizr DSL.
2. Generate PlantUML diagrams using Structurizr CLI.
3. Generate HTML documentation using Asciidoctor.
4. Serve the documentation using Nginx or GitHub Pages.

Prerequisites

• Docker
• Docker Compose

Technologies Used

• arc42 template: Used to define a structure of documentation.
• Structurizr DSL: Used to define the architecture model.
• Structurizr CLI: Used to export PlantUML diagrams from Structurizr DSL.
• PlantUML: Used to generate UML diagrams.
• AsciiDoc: Used as a markup language for documents.
• Asciidoctor: Used to convert AsciiDoc files to HTML.

Directory Structure

architecture-docs/
├── src/                                # Source files for documentation
│   └── docs/                           # Documentation source directory
│       ├── asciidoc/                   # AsciiDoc files
│       │   ├── sections/               # Individual section files for arc42 template
│       │   │   ├── 01_introduction_and_goals.adoc
│       │   │   ├── ...
│       │   └── index.adoc              # Main AsciiDoc file including all sections
│       ├── structurizr/                # Structurizr DSL files and generated PlantUML diagrams
│       │   ├── structurizr.dsl
│       │   ├── structurizr.properties
│       │   ├── ... Generated PUML files
├── .github /                           # GitHub Workflows
│   └── docs/       
│       ├── deploy-confluence.yaml      # Deploy to Confluence Workflow
│       └── deploy-docs.yaml            # Deploy to GitHub Pages Workflow

Usage

Follow these steps to generate and serve the architecture documentation.

1. Generate PlantUML diagrams

Run the following command to generate PlantUML diagrams from the Structurizr DSL:

docker-compose run --rm generate-diagrams

2. Generate HTML documentation

Run the following command to generate the HTML documentation:

docker-compose run --rm generate-docs

3. Serve the documentation

Run the following command to serve the documentation using Nginx:

docker-compose up serve-docs

4. View the documentation

Open your browser and go to http://localhost:8080 to view the generated documentation.

GitHub Pages Demo

You can view the demo of this documentation on GitHub Pages at the following URL.

Customization

You can customize the Structurizr DSL file (structurizr.dsl) to reflect your own system's architecture. Similarly, you can edit the AsciiDoc files in the sections directory to include more detailed information about your system.

Wrap Up

If you think the repository can be improved, please open a PR with any updates and submit any issues. Also, I will continue to improve this, so you should star this repository, too.

Contribution

• Open a pull request with improvements
• Discuss ideas in issues
• Spread the word

License

Author

Dr. Milan Milanović - CTO at 3MD