{"id":20200369,"url":"https://github.com/riduidel/aadarchi","last_synced_at":"2025-12-11T20:57:44.971Z","repository":{"id":37703038,"uuid":"215797697","full_name":"Riduidel/aadarchi","owner":"Riduidel","description":"A maven archetype to generate easily projects allowing architecture description using a mix of C4, agile architecture, Asciidoc and PlantUML","archived":false,"fork":false,"pushed_at":"2024-07-10T13:56:36.000Z","size":12358,"stargazers_count":43,"open_issues_count":29,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T22:41:16.486Z","etag":null,"topics":["architecture-documentation","asciidoc","hacktoberfest","java","structurizr"],"latest_commit_sha":null,"homepage":"https://riduidel.github.io/aadarchi/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Riduidel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-17T13:21:20.000Z","updated_at":"2025-02-24T02:19:27.000Z","dependencies_parsed_at":"2024-02-18T17:48:37.164Z","dependency_job_id":"cc21eff6-e196-4bee-84a3-37d02e929085","html_url":"https://github.com/Riduidel/aadarchi","commit_stats":null,"previous_names":["riduidel/agile-architecture-documentation-system"],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riduidel%2Faadarchi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riduidel%2Faadarchi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riduidel%2Faadarchi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riduidel%2Faadarchi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Riduidel","download_url":"https://codeload.github.com/Riduidel/aadarchi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250388017,"owners_count":21422246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture-documentation","asciidoc","hacktoberfest","java","structurizr"],"created_at":"2024-11-14T04:43:22.788Z","updated_at":"2025-04-23T07:23:14.912Z","avatar_url":"https://github.com/Riduidel.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to Aadarchi 👋\n\n[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/Riduidel/aadarchi/on_push_on_master_deploy_build.yml)](https://github.com/Riduidel/aadarchi/actions/workflows/on_push_on_master_deploy_build.yml)\n[![GitHub version](https://badge.fury.io/gh/Riduidel%2Faadarchi.svg)](https://badge.fury.io/gh/Riduidel%2Faadarchi)\n![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/m/Riduidel/aadarchi)\n![Mastodon Follow](https://img.shields.io/mastodon/follow/000004227?domain=https%3A%2F%2Fframapiaf.org)\n\n\u003e A Maven archetype allowing you to easily create your agile architecture documentation using a mix of C4, Asciidoc and PlantUML. This archetype uses [Structurizr](https://github.com/structurizr/java/) to build the architecture model, and [Agile architecture documentation](https://web.archive.org/web/20210518020154/http://www.codingthearchitecture.com/2016/05/31/agile_software_architecture_documentation.html) template, all by Simon Brown.\n\n## Install\n\nYou can use the archetype by running this maven-friendly 😅command.\nCurrent version is ![GitHub version](https://badge.fury.io/gh/Riduidel%2Faadarchi.svg)\n\n```sh\nmvn archetype:generate -DarchetypeVersion=0.2.3 -Daadarchi-version=0.2.3 -DarchetypeGroupId=io.github.Riduidel.aadarchi -DarchetypeArtifactId=archetype \n```\n\nThis will ask you a few questions and generate the project.\nFinally, don't forget to replace the value of `aadarchi-version` maven property by ![GitHub version](https://badge.fury.io/gh/Riduidel%2Faadarchi.svg)\n\n## Usage\n\nOnce the archetype has been run, you'll have a project with a Structurizr `workspace.dsl` file in `src/architecture/resources` (conform to [Structurizr DSL syntax](https://github.com/structurizr/dsl/blob/main/docs/language-reference.md), which means that file can be viewed using [Structurizr-lite](https://dev.to/simonbrown/getting-started-with-structurizr-lite-27d0))\nand asciidoc files following Agile architecture documentation template in `src/docs/asciidoc`.\n\n### Generating architecture documentation\nRunning `mvn install` will \n\n1. compile and run Java code to have C4 model-compatible diagrams generated by PlantUML\n1. generate AsciiDoc HTML and PDF files\n\n### Faster edit loop\nA faster developer feedback loop can be achieved using our own aadarchi-maven-plugin (already configured in the archetype POM).\nYou can run `mvn -Plivereload` when working on documents.\nThis will watch the folders \n`src/docs/asciidoc` (if it exists), \n`src/slides/asciidoc` (if it exists), \n`src/main/java` (if it exists), \nand `src/architecture/resources` (if it exists)\nand run a `mvn package` when any of these folders have changes in.\n\nVisit [http://localhost:35729/docs/html/](http://localhost:35729/docs/html/) to view your generated slides in HTML form.\nVisit [http://localhost:35729/slides/html/](http://localhost:35729/slides/html/) to view your generated slides in HTML form.\n\nIf you have installed the [livereload browser extension](http://livereload.com/extensions/) (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)\n\n### Best practices\n* Define systems, containers and components options **only** through structurizr properties. \nThe useful method for that is `ModelItem#addProperty(String, String)`. \nDon't try to load properties from other means, cause it'll introduce incoherence.\n* Try to stay close to describe=\u003eextend=\u003egenerate. In other words, first describe architecture in `Architecture` class (or `workspace.dsl` if you prefer the Structurizr DSL syntax). \nThen use available extension points (provided by CDI) to add additional infos.\n\n#### describe=\u003eextend=\u003egenerate\nWhat are we talking about here ?\nIn fact, the simplest way to have a good model, from what we've already tested, is to\n\n1. Create a valid and complete model, by either describing all elements or finding them (using enhancers like `MavenDetailsInfererEnhancer`)\n2. Extend that model by adding associated resources (that's typically the case of the `SCMLinkGenerator` and `SCMReadmeReader`)\n3. Generate the good resources, like the views (using the archetype provided `ViewsGenerator`) and the document includes\n\n#### Writing an Enhancer\nSince we're talking about the `Enhancer` interface, this is the main interface allowing us to have an extendable architecture model.\nSo how to write an `Enhancer` ? \nFirst, choose what to enhance: model or views ? \nBoth of them have dedicated subinterfaces (`ModelEnhancer` and `ViewEnhancer`).\nThere even is a `ModelElementAdapter` that will ease things out for model enhancers, since it's the interface you may extend.\nSo, once you've chosen what to extend, choose when this enhancer will run by setting a priority.\nThis priority defines the order in which the enhacer will run, and all running enhancers are displayed ordered by priority at start of generation.\nNow, you'll have to implement the visiting methods, for which you can find numerous examples in our code.\nDon'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.\n\n## Developing\nThere are not many things to do (except improving the archetype source).\nHowever, if you want to improve things, \nplease run `mvn verify` which will create a project from the archetype and \nrun `mvn package` which will trigger Java class compilation and run and Asciidoc documentation generation.\n\n### Releasing\nCan be performed only on a machine having Nicolas Delsaux GPG key allowing to sign to maven central (not yet enabled on GitHub).\n\nDon't forget to activate the `-Prelease` profile, which enable all the good things (Sonatype staging, signing, ...)\n\n## Architecture\nWay more details are available in the [architecture documentation (which uses this system, obviously)](https://riduidel.github.io/aadarchi/).\n\n## Author\n\n👤 **Nicolas Delsaux**\n\n* Mastodon: [@Riduidel](https://framapiaf.org/@Riduidel)\n* Github: [@Riduidel](https://github.com/Riduidel)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/Riduidel/aadarchi/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n***\n_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friduidel%2Faadarchi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friduidel%2Faadarchi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friduidel%2Faadarchi/lists"}