Improve project documentation

CONTRIBUTING.md

@@ -1,12 +1,13 @@
 # Contributing to DGA
 
-Pull requests (PR) are welcome. Here are some tips to consider to land new PR in the main branch.
+Pull requests (PR) are very welcome. Here are some tips to consider to land new PR in the main
+branch.
 
 ## Ways to contribute
 
 You can help make DGA a better tool by:
 
-* Raise an issue if you discover a bug.
+* Raise an issue if you discover a bug or when you miss a feature.
 * Contribute bug fixes, new features or enhancements.
 
 ## Before opening a PR
@@ -16,7 +17,11 @@ the problem being solved and the implementation design can be discussed. This he
 being invested in code that is never eventually merged, and also promotes better designs by
 involving the community more widely.
 
-For straightforward bug fixes where the issue is clear and can be illustrated via a failing unit,
-please just open a PR.
+For straightforward bug fixes where the issue is clear and can be illustrated via a failing unit
+test, please just open a PR.
 
-Make sure `./gradlew check` passes.
+## Tips
+
+* Read the [project documentation](docs) to better understand the software architecture and how the
+  project actually works.
+* Add unit tests and make sure they pass `./gradlew check`

README.md

@@ -1,7 +1,6 @@
 # DGA: Dependency Graph Analyser
 
-[![Verify project](https://github.com/ryru/dependency-graph-analyser/actions/workflows/verify.yml/badge.svg)](https://github.com/ryru/dependency-graph-analyser/actions/workflows/verify.yml)
-[![Build project](https://github.com/ryru/dependency-graph-analyser/actions/workflows/build.yml/badge.svg)](https://github.com/ryru/dependency-graph-analyser/actions/workflows/build.yml)
+[![Build (assemble & check)](https://github.com/ryru/dependency-graph-analyser/actions/workflows/build.yml/badge.svg)](https://github.com/ryru/dependency-graph-analyser/actions/workflows/build.yml)
 
 Analyse and visualise module dependencies in Gradle projects.
 
@@ -140,10 +139,20 @@ graph TD
 
 - Use `--transitive` to also include transitive dependencies.
 
-## How DGA works
+## Documentation
 
-See [HowItWorks.md](HOWITWORKS.md)
+See [docs](docs) for project documentation.
 
 ## Contribution
 
-Pull requests are welcome! Check [CONTRIBUTING.md](CONTRIBUTING.md) before starting any work.
+Contributions are very welcome! Check [CONTRIBUTING](CONTRIBUTING.md) before starting any work.
+
+## Motivation and goal
+
+I started this hobby project primarily to learn and practice Kotlin, while also deepening my
+understanding of Gradle and its build system.
+
+I'm currently working on a medium to large software project consisting of several dozen Gradle
+modules. Having recently discovered Mermaid, I thought it would be useful to create a tool that can
+visualise and analyse dependencies in larger Gradle projects. The goal of this tool, _DGA_, should
+be to help to better understand the relationships between different modules.

docs/01-Architecture.md

@@ -0,0 +1,46 @@
+# Architecture
+
+Describes the current software architecture of this project.
+
+```mermaid
+---
+title: Gradle Project Overview
+---
+graph TB
+    app --> core
+    app --> importer
+    importer --> connector-model
+    importer --> core
+    connector-plugin --> connector-model
+```
+
+- **app**: Contains the CLI application that parses the input, starts the dependency injection
+  modules and prints the output.
+- **core**: Contains the core logic to analyse projects.
+- **importer**: Responsible to connect to a gradle project and provides the analysed data model to
+  the CLI application core logic.
+- **connector-plugin**: The Gradle custom plugin that is injected into the analysed Gradle build.
+- **connector-model**: The data model of the analysed Gradle build.
+
+## How it works
+
+DGA uses
+the [Gradle Tooling API](https://docs.gradle.org/current/userguide/third_party_integration.html#how_to_integrate_with_gradle)
+to connect to an existing Gradle project and uses an init script to inject the connector plugin into
+all Gradle projects. The plugin reads the project title, all Gradle projects and parses all project
+dependencies and provides this information in a dependency model back to the CLI application.
+
+## Artefacts releasing and publication
+
+- DGA CLI application is published
+  to [GitHub](https://github.com/ryru/dependency-graph-analyser/releases) by setting a git version
+  tag and pushing to the main branch.
+- DGA connector plugin is published by manually executing the
+  GitHub [Release Connector Plugin](https://github.com/ryru/dependency-graph-analyser/actions/workflows/releaseConnectorPlugin.yml)
+  CI pipeline. Artefacts are relesed to
+  the [Gradle Plugin repositor](https://plugins.gradle.org/plugin/ch.addere.dga.connectorplugin)
+
+The versions are defined in the [gradle.properties](../gradle.properties) file.
+
+The version of the DGA connector plugin needs to be updated as soon as the plugin or the model
+changes.