wonderbird/malimo

// To always get the latest diagrams, update the
// commit hash from the version merged into main
:gitplant: http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/wonderbird/malimo/b8225458c833ce1da36c998a820a9f0bed06150a/docs/plantuml

= Architecture

:icons: font

:toc:

== Acknowledgements

This documentation is based on the https://docs.arc42.org[arc42] template. The examples provided there and in
https://www.dokchess.de/["DokChess als Beispiel für arc42"] act as templates for some sections. Many thanks to all
contributors for your valuable work.

The architecture document is grown as needed. Chapter numbers follow the suggestions from
https://docs.arc42.org[arc42]. Numbering gaps are a consequence.

== 3 Business Context

.Business Context
image::{gitplant}/business-context.puml[Business Context]

The diagram above shows the roles of the different user groups. It also shows the dependency of the system:

[cols="1,4"]
|===
|User
|use the command line interface application "malimo" (CLI) to move all images used by a markdown file into a folder

|Administrator
|install and maintain the CLI application on the user's computer

|User's filesystem
|the CLI operates in the local filesystem of the user's computer
|===

== 5 Composite Structure

The individual components making up the malimo system are depicted below:

.Composite Structure
image::{gitplant}/composite-structure.puml[Composite Structure]

[cols="1,4"]
|===
| malimo
| CLI application allowing users to invoke the operations of the Markdown Linked Images Mover system

| malimo.rb
| https://brew.sh[Homebrew] cask allowing allowing administrators to install the malimo application on macOS. This file is available in the separate GitHub repository https://github.com/wonderbird/homebrew-tools[wonderbird / homebrew-tools]. 

| chocolatey
| The link:../chocolatey[chocolatey folder] contains the https://docs.chocolatey.org/en-us/create/create-packages[Chocolatey package definition], which allows administrators to install the malimo application on Windows.
|===

== 7 Deployment View

.Deployment View
image::{gitplant}/deployment-view.puml[Deployment View]

=== 7.1 Administrator View: Install malimo

The application supports macOS on ARM64 ("Apple Silicon") and Intel CPUs and Windows on Intel CPUs.

For macOS, a private https://brew.sh[Homebrew] tap is available in https://github.com/wonderbird/homebrew-tools[wonderbird/homebrew-tools]. The cask `malimo.rb` allows installing the latest macOS version. It detects the host platform and downloads the associated "bottle" from the https://github.com/wonderbird/malimo/releases[malimo releases] page.

For Windows, a https://community.chocolatey.org/packages/malimo[Chocolatey package] is available in the https://community.chocolatey.org/[Chocolatey Community Repository]. As an alternative, the software administrator can download the latest ZIP file from the https://github.com/wonderbird/malimo/releases[malimo releases page]. The files shall be extracted to a folder which is added to the `PATH` environment variable.

=== 7.2 Maintainer View: Update Application Icon

The application icon is referenced by `<iconUrl>` entry in the Chocolatey package configuration file link:../chocolatey/malimo.nuspec[malimo.nuspec].

=== 7.3 Maintainer View: Publish a New Release

==== Prerequisite

- The link:../CHANGELOG.md[CHANGELOG.md] must be up-to-date.

==== Trigger the Release Pipeline

After a pull request has been merged to `main`, create and push a version tag:

```shell
git checkout main
git pull
git tag -a "v0.1.5-alpha" -m "v0.1.5-alpha"
git push --tags
```

This will trigger the full link:../.github/workflows/dotnet.yml[GitHub Action to publish a new release]. The workflow will finally produce the https://github.com/wonderbird/malimo/releases[GitHub release], attach the installation packages for the target operating systems and push the Chocolatey package to the community repository.

NOTE: It usually takes about 1 hour until the updated Chocolatey package is available.

==== Abort Release Making

If the pipeline fails, then the release should be rolled back:

1. To save some energy, abort the corresponding GitHub action, if it is still running
2. Delete the corresponding tag from the https://github.com/wonderbird/malimo/tags[GitHub tags] page
3. Delete the tag from all local working directories: `git tag -d "v0.1.5-alpha"`

Now you can start over.

==== Update Homebrew Tools

After a successful release, update corresponding cask in the https://github.com/wonderbird/homebrew-tools[Homebrew tap wonderbird/tools]:

. Download the release artifacts for macOS, e.g. to `~/Downloads/malimo*`
. `shasum -a 256 ~/Downloads/malimo*`
. Update the `version` and `sha256` entries for the new release
. Test the update locally using `brew upgrade malimo`
. Publish the changes
. Ensure the test pipelines are green