All Collections
Always up-to-date architecture documentation
Always up-to-date architecture documentation

This document helps you to understand how to achieve always up-to-date architecture documentation with help of automation.

Ville Laitila avatar
Written by Ville Laitila
Updated over a week ago

Process of utilizing architecture documentation automation process when using Softagram.

Capabilities of automated architecture analysis in Softagram

  • Static dependencies

  • Source code directory structure

  • Dockerfile, pom.xml, package.json, etc. indexing

  • Source code size measurements (lines of code)

  • Common vocabulary for software components (directory names, file names, class names) that is based on what exists in the version control system.

  • Dependency metrics, architecture metrics

  • Used open source

  • Model comparison alias architecture diff

What up-to-date architecture model enables

  • Identify responsibilities of each component based on its dependencies and contents

  • Identify the most critical components

  • Identify the most problematic components (changing often, causing trouble)

  • Navigate dependency chains, find cyclic dependencies (harmful for good clean architecture)

  • Identify anti-patterns such as God Component/Class

  • Shifting software design process toward fact-based direction (vs. opinion based)

  • Help splitting monolithic components or upgrade dependencies

... shortly, keep software Fit.

Out-of-scope in automated architecture analysis

  • dynamic behavior of the software (e.g. sequences, order of operations)

  • method internals and function internals (low level stuff)

  • use case modelling (it is impossible to extract use cases or requirements from source code)

Recommendations when the goal is to combine manual and automated architecture documentation

  • Avoid funny synonyms for components, use strictly clean and unambiguous, distinct names for things

  • Document sequences, state diagrams, use cases etc. in some modern easy-to-change documentation system such as Wiki. When referencing components from the documentation, have full path references if there is any room for ambiguity.


     Coming Sooner or Later:

  • JSON-based format for describing the future changes (e.g. deprecations, removals, new APIs, dependency changes, etc.), and capability to reflect its information on top of the most recent architecture model.

Below screenshot shows how you can enable analysis for your project, and configure the "unmerged branches" setting to fit your needs. For example, if you have branches dev and trunk that you want to follow, you can define those branch names in settings with Analyse only these branches setting.

Did this answer your question?