1. Context
| If you encounter any error, feel free to enter an issue on GitHub. |
aadarchi-documentation-system tries to provide a solution to a rather usual, but not so well solved, problem: how to document architecture of a software system with the minimal effort and the maximal result. As a consequence, this product tries to help the architect in all possible ways.
1.1. Context diagram
We identify different user profiles:
-
the architect as a scribe role, which is responsible for maintaining a correct documentation of the architecture
-
the various stakeholders, be them developers, product owners, ops teams, and so on, which will refer to the produced documentation as an entrypoint.
2. Functional Overview
| If you encounter any error, feel free to enter an issue on GitHub. |
This software helps the architect writing a coherent, complete and readable software architecture documentation. Usage of this software is quite simple (for a developer).
The first step is to initiate a documentation (which is documented in README.md).
Then, architect has to write content in all .adoc files generated in src/docs/asciidoc.
Notice writing those files will be eased out by using the Architecture java class to generate diagrams,
and the enhancers this project provides.
The enhancers allows architect to have content added to this documentation without having to write it himself. Typically, we’re able to include README documents, architecture decisions, and more to come later … (well, provided the users ask for additionnal includes)
3. Quality Attributes
| If you encounter any error, feel free to enter an issue on GitHub. |
The documentation build should be fast enough to allow architect to write its documentation and have it reloaded in "human real time". In other words, we expect a simple documentation to generate in less than 10 seconds and a complex documentation (involving reading configuration from remote systems and so on) to generate in less than 1 minute. TODO
4. Constraints
| If you encounter any error, feel free to enter an issue on GitHub. |
TODO
5. Principles
| If you encounter any error, feel free to enter an issue on GitHub. |
-
Architecture model must be totally described in the Architecture class.
-
Additional architecture information (typically, location of README files for components) has to be set has properties in the various Structurizr
Elementsubclasses (SoftwareSystem,Container,Component)
6. Software Architecture
7. Code
| If you encounter any error, feel free to enter an issue on GitHub. |
7.1. Aadarchi
| Priority | Enhancer |
|---|---|
0 |
|
1 |
|
10 |
|
10 |
|
50 |
|
99999 |
|
99999 |
|
100000 |
|
100001 |
|
100001 |
|
100002 |
|
100002 |
|
100005 |
|
2147483646 |
|
2147483646 |
|
2147483647 |
|
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Architect The architect as team scribe is the writer of this kind of documentation. |
Bootstrap a valid project |
Base module of a set of tools created to allow easy architecture documentation based upon Simon Brown work. |
Read generated documentation |
Stakeholder All project stakeholders are readers of this kind of documentation. |
7.1.1. aadarchi-maven-plugin
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
archetype Easily create configuration to document your project with this archetype architecture-documentation maven The maven build engine |
Generates a pom.xml using this plugin Generates architecture diagrams Generates documentation artifacts Invokes this plugin during build to generate data |
This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
Reads maven pom details Runs the ArchiectureEnhancer class Starts CDI in maven |
asciidoc The asciidoctor engine base Base module defining the various used interfaces, and some very useful implementations cdi-in-maven-plugin-helper This small java library provides a simple way to have a maven Mojo use CDI for bean injection maven-metadata-inferer A module allowing as much informations as possible to be read from Maven POM |
7.1.2. aadarchi-test-utils
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
base Base module defining the various used interfaces, and some very useful implementations freemarker-cdi-producer This CDI producer allows easy usage of Freemarker in a CDI-compatible application. maven-metadata-inferer A module allowing as much informations as possible to be read from Maven POM model-linter A model linter that verify if some useful things are present in an element. sequence-diagram-generator Generates sequence diagrams for components in the containers opting in for it. Model elements in those sequence diagrams should also be indicated by containers. sipoc-diagram-generator Generates SIPOC (suppliers/inputs/process/outputs/consumers) diagrams in an asciidoc table, for each element. |
Eases CDI tests maven:dependency |
Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests |
maven:dependency |
cdi-config-extension Some CDI extensions |
7.1.3. adr-tickets-extractor
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Provides mechanisms to initialize repository elements AND include project ADR from GitHub issues |
Uses Ticket reader interface maven:dependency |
base Base module defining the various used interfaces, and some very useful implementations freemarker-cdi-producer This CDI producer allows easy usage of Freemarker in a CDI-compatible application. |
7.1.4. archetype
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Architect The architect as team scribe is the writer of this kind of documentation. |
Bootstrap a valid project |
Easily create configuration to document your project with this archetype |
Generates a pom.xml using this plugin Generates documentation project |
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos architecture-documentation |
7.1.5. architecture-documentation
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
archetype Easily create configuration to document your project with this archetype |
Generates documentation project |
Generates architecture diagrams Generates documentation artifacts Read generated documentation |
Stakeholder All project stakeholders are readers of this kind of documentation. aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
7.1.6. asciidoc
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
The asciidoctor engine |
7.1.7. base
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos adr-tickets-extractor Provides mechanisms to initialize repository elements AND include project ADR from GitHub issues maven-metadata-inferer A module allowing as much informations as possible to be read from Maven POM model-linter A model linter that verify if some useful things are present in an element. sequence-diagram-generator Generates sequence diagrams for components in the containers opting in for it. Model elements in those sequence diagrams should also be indicated by containers. sipoc-diagram-generator Generates SIPOC (suppliers/inputs/process/outputs/consumers) diagrams in an asciidoc table, for each element. spring-components-detector Component allowing detection of Spring components in a Spring technology based container. structurizr-components-detector A component detector that uses Structurizr annotations to find existing components and their relationship. |
Runs the ArchiectureEnhancer class Uses Enhancer interface Uses Ticket reader interface maven:dependency |
Base module defining the various used interfaces, and some very useful implementations |
Converts Markdown files to Asciidoc Eases CDI tests Exposes maven properties as CDI ones |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests cdi-config-extension Some CDI extensions markdown-to-asciidoc |
AddDependenciesFromProperties
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
ArchitectureEnhancer |
Enhances architecture |
ArchitectureDocumentationBuilder
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Adds information to initial architecture description |
ArchitectureEnhancer |
ArchitectureEnhancer
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
ArchitectureDocumentationBuilder |
Adds information to initial architecture description |
Enhances architecture |
AddDependenciesFromProperties DocumentsCollector GraphEmitter ImplicitIncludeManager ReadmeReader SCMLinkGenerator ToDsl |
DocumentsCollector
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
ArchitectureEnhancer |
Enhances architecture |
ImplicitIncludeManager
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
ArchitectureEnhancer |
Enhances architecture |
7.1.8. cdi-config-extension
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests base Base module defining the various used interfaces, and some very useful implementations cdi-in-maven-plugin-helper This small java library provides a simple way to have a maven Mojo use CDI for bean injection freemarker-cdi-producer This CDI producer allows easy usage of Freemarker in a CDI-compatible application. |
Exposes maven properties as CDI ones maven:dependency |
Some CDI extensions |
7.1.9. cdi-in-maven-plugin-helper
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
Starts CDI in maven |
This small java library provides a simple way to have a maven Mojo use CDI for bean injection |
maven:dependency |
cdi-config-extension Some CDI extensions |
7.1.10. freemarker-cdi-producer
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
adr-tickets-extractor Provides mechanisms to initialize repository elements AND include project ADR from GitHub issues |
maven:dependency |
This CDI producer allows easy usage of Freemarker in a CDI-compatible application. |
maven:dependency |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests cdi-config-extension Some CDI extensions |
7.1.11. markdown-to-asciidoc
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
base Base module defining the various used interfaces, and some very useful implementations |
Converts Markdown files to Asciidoc |
null |
7.1.12. maven
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Architect The architect as team scribe is the writer of this kind of documentation. |
Generates documentation |
The maven build engine |
Invokes this plugin during build to generate data |
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
7.1.13. maven-metadata-inferer
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
aadarchi-maven-plugin This maven plugin allows integration of our documentation system into maven builds by providing a set of useful mojos |
Reads maven pom details |
A module allowing as much informations as possible to be read from Maven POM |
Eases CDI tests Uses Enhancer interface |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests base Base module defining the various used interfaces, and some very useful implementations |
7.1.14. model-linter
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
A model linter that verify if some useful things are present in an element. |
Eases CDI tests Uses Enhancer interface |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests base Base module defining the various used interfaces, and some very useful implementations |
7.1.15. sequence-diagram-generator
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Generates sequence diagrams for components in the containers opting in for it. Model elements in those sequence diagrams should also be indicated by containers. |
Eases CDI tests Uses Enhancer interface |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests base Base module defining the various used interfaces, and some very useful implementations |
7.1.16. sipoc-diagram-generator
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Generates SIPOC (suppliers/inputs/process/outputs/consumers) diagrams in an asciidoc table, for each element. |
Eases CDI tests Uses Enhancer interface |
aadarchi-test-utils Some test utilities dedicated to the improvement of Aadarchi quality. Mainly contains tools allowing easy injection of Maven properties into tests base Base module defining the various used interfaces, and some very useful implementations |
7.1.17. spring-components-detector
| Incoming | Input | Process | Output | Outgoing |
|---|---|---|---|---|
Component allowing detection of Spring components in a Spring technology based container. |
Uses Enhancer interface |
base Base module defining the various used interfaces, and some very useful implementations |
8. Data
| If you encounter any error, feel free to enter an issue on GitHub. |
Application hosts no data other, since verything is in the Maven folder.
9. Infrastructure Architecture
| If you encounter any error, feel free to enter an issue on GitHub. |
The main goal of this application is to produce content that can be browsed as HTML or PDF. As a consequence, there is no requirement for any production infrastructure.
10. Deployment
| If you encounter any error, feel free to enter an issue on GitHub. |
Deployment of the aadarchi-documentation code is done by pushing code to GitHub. On push, there is a GitHub action (defined in main module .github folder) which will compile everything and generate the github pages.
11. Development Environment
| If you encounter any error, feel free to enter an issue on GitHub. |
Development of this documentation solution requires a Java environnment. In other words, you need
-
A recent JDK (at least Java 11)
-
Maven (at least version 3.6)
-
A Java IDE
Optionally, things will be better if you have
-
an Asciidoc editor
12. Operation and Support
| If you encounter any error, feel free to enter an issue on GitHub. |
TODO
13. Decision Log
| If you encounter any error, feel free to enter an issue on GitHub. |
13.1. Use ADR to document architecture decisions
Date: 2020-01-14
We will store decisions as asciidoc documents in src/docs/asciidoc/decisions.
Accepted
The purpose of this section is to simply record the major decisions that have been made, including both the technology choices (e.g. products, frameworks, etc) and the overall architecture (e.g. the structure of the software, architectural style, decomposition, patterns, etc). For example:
-
Why did you choose technology or framework "X" over "Y" and "Z"?
-
How did you do this? Product evaluation or proof of concept?
-
Were you forced into making a decision about "X" based upon corporate policy or enterprise architecture strategies?
-
Why did you choose the selected software architecture? What other options did you consider?
-
How do you know that the solution satisfies the major quality attributes?
-
…
-
Decisions will be integrated in generated documentation
-
Rendering will be optimal
-
Decisions will be burried deep inside Asciidoc hiearchy
-
Decisions can be put in a specific folder
-
We can use "tooling" to access those decisions
-
Decisions will be isolate from architecture documentation
-
Decision rendering will use another tooling (typically Markdown)
-
Integrating decisions in Asciidoc requires changing a section of architecture.