Welcome to Agile architecture documentation archetype 👋

A Maven archetype allowing you to easily create your agile architecture documentation using a mix of C4, Asciidoc and PlantUML. This archetype uses Structurizr to build the architecture model, and Agile architecture documentation template, all by Simon Brown.

Install

You can use the archetype by running this maven-friendly 😅command. Don't forget to replace ${VERSION} by

mvn archetype:generate -DarchetypeGroupId=io.github.Riduidel.agile-architecture-documentation-system -DarchetypeArtifactId=archetype -DarchetypeVersion=${VERSION}

This will ask you a few questions and generate the project. Finally, don't forget to replace the value of agile-architecture-version maven property by

Usage

Once the archetype has been run, you'll have a project with Structurizr compatible source in src/main/java and asciidoc files following Agile architecture documentation template in src/docs/asciidoc.

Generating architecture documentation

Running mvn install will

1. compile and run Java code to have C4 model-compatible diagrams generated by PlantUML
2. generate AsciiDoc HTML and PDF files

Using the archetype at 100%

The archetype contains two Java classes.

1. Architecture contains initial definition of your architecture. This is where you should put all the systems, containers, components that are directly described.
2. ViewsGenerator allow you to generate the various views by using elements of the architecture model.

Faster edit loop

A faster developer feedback loop can be achieved using the fizzed-watcher-maven-plugin. Don't worry, you don't have to configure it by yourself! You can run mvn -Plivereload when working on documents. This will watch both the src/docs (if it exists), src/slides (if it exists) and the src/main/java folder and run a mvn package when any of these folders have changes in.

Visit http://localhost:35729/docs/html/ to view your generated slides in HTML form. Visit http://localhost:35729/slides/html/ to view your generated slides in HTML form.

If you have installed the livereload browser extension (but not the livereload desktop application, which job is handled by the maven build), any change in the project will be immedialety visible in browser, allowing you to work in a pleasant environment (well, I hope)

Best practices

• Define systems, containers and components options only through structurizr properties. The useful method for that is ModelItem#addProperty(String, String). Don't try to load properties from other means, cause it'll introduce incoherence.
• Try to stay close to describe=>extend=>generate. In other words, first describe architecture in Architecture class. Then use available extension points (provided by CDI) to add additional infos.

describe=>extend=>generate

What are we talking about here ? In fact, the simplest way to have a good model, from what we've already tested, is to

1. Create a valid and complete model, by either describing all elements or finding them (using enhancers like MavenDetailsInfererEnhancer)
2. Extend that model by adding associated resources (that's typically the case of the SCMLinkGenerator and SCMReadmeReader)
3. Generate the good resources, like the views (using the archetype provided ViewsGenerator) and the document includes

Writing an Enhancer

Since we're talking about the Enhancer interface, this is the main interface allowing us to have an extendable architecture model. So how to write an Enhancer ? First, choose what to enhance : model or views ? Both of them have dedicated subinterfaces (ModelEnhancer and ViewEnhancer). There even is a ModelElementAdapter that will ease things out for model enhancers, since it's the interface you may extend. So, once you've chosen what to extend, choose when this enhancer will run by setting a priority. This priority defines the order in which the enhacer will run, and all running enhancers are displayed ordered by priority at start of generation. Now, you'll have to implement the visiting methods, for which you can find numerous examples in our code. Don't forget to take a look at the isParallel() method, which may fasten things a lot, since it can allow the enhancer to be run using parallel features of Java system executor services.

Developing

There are not many things to do (except improving the archetype source). However, if you want to improve things, please run mvn verify which will create a project from the archetype and run mvn package which will trigger Java class compilation and run and Asciidoc documentation generation.

Releasing

Can be performed only on a machine having Nicolas Delsaux GPG key allowing to sign to maven central (not yet enabled on GitHub).

Don't forget to activate the -Prelease profile, which enable all the good things (Sonatype staging, signing, ...)

Architecture

Way more details are available in the architecture documentation (which uses this system, obviously).

Author

👤 Nicolas Delsaux

• Twitter: @Riduidel
• Github: @Riduidel

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

This README was generated with ❤️ by readme-md-generator