Skip to content

Software Architecture Documentation Template Hits

You can access the generated documentation here (demo), it's based on a sample you can download at arc42.org.

sequenceDiagram
    title Sample Mermaid Diagram
    box Purple Alice & John
    participant A
    participant J
    end
    box Another Group
    participant B
    participant C
    end
    A->>J: Hello John, how are you?
    J->>A: Great!
    A->>B: Hello Bob, how is Charley?
    B->>C: Hello Charley, how are you?

Capabilities

  • Arc42 - the documentation template in place, link.
  • Mermaid - used for diagramming to better illustrate your software architecture, link.
  • C4 Model - For context and container representation of your systems, link.
  • Mkdocs Material - is being used as the static site generator along with the material template, link.
  • GitHub Action - CI/CD in place to deploy the documentation as a GitHub Page site.

Commands

  • pip install -r requirements.txt - install the dependencies.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    diagrams  # Folder containing your Mermaid and C4 diagrams.
    decisions # The location of your architecture decisions records.
    images    # Images displayed in the pages.
    css/js    # To be used only if you need to customize the site.
    .github   # GitHub Action CI/CD pipeline.
    ...       # Other markdown pages, images and other files.

TODO

  • [x] Fix the GitHub Page link.
  • [ ] Generate a PDF version of the software architecture documentation.