devonfw / solutions

Architectures / Pattern Catalog of devonfw

This catalog is maintaining the sources for the architectures website section.

If you want to edit this repository in the cloud, please click here.

How to create a new architecture

To create a new architecture, copy over the solution-template.asciidoc file from the root of the repository to a newly created folder within https://github.com/devonfw/solutions/tree/master/solutions. For ease of use, the folder name should encode at least the name of your architecture sample / pattern. Afterwards, rename the solution-template.asciidoc file to index.asciidoc to make it be generated properly.

Tags

You can setup any tags of your choice on top of the asciidoc file as comments. At the moment the copy template provides the two tags Category and Product. Multiple values for one tag can be separated by colon. It's possible to add additional tags on demand by simply create a new line of key and value pair.

Please add the tag Maturity level and set it to one of the values Initial, Advanced, Complete to describe the progress of the architecture description.

//Category=coolCategory 2
//Product=A cool product 2;Coolest product
//Maturity level=Complete

Includes Folder

The common solution snippets are placed in the includes folders. Each snippet has its own folder in the includes folder. The snippet folders should contain an asciidoc file and the files (e.g. images) used by this snippet.

solutions's Issues

Add recommendations for authorization

Create new documentation in the solutions folder for authorization aspects/patterns.

Orientations:
https://github.com/devonfw/devon4j/blob/master/documentation/guide-access-control.asciidoc

Opentelemetry generic helm template for AKS and EKS

Observability solution with istio in the solution browser

As an Architect,
I want to have a ready to use solution for making my services in kubernetes easier to oobserve using istio,
so that I can decide if istio is the right tool to use and I can integrate it in devonfw easily.

The solution should contain a short description of istio and important links. Furthermore, it should contain a description what problems it can solve as well (links to other solutions if available).

The solution should contain links to a setup description (or if that is not available a setup description with helm charts) for production ready deployment.

Things to consider

• Setup a local istio in your cluster and automate that installation with IaC (propably helm)
• Interview istio users about their setup
  • What are the common pitfalls
  • Things to consider for production ready setup
  • Common issues that should be documented

Istio solution - alternatives

What are alternatives to the solution are existing?

Add preview to PRs

As a PR creator, I want to see how my solution would look like before the PR is merged so I can see that everything looks like I want it to look.

Links that could be helpful:
https://www.npmjs.com/package/node-html-to-image
https://github.com/marketplace/actions/workflow-artifact-pull-request-comment

Write a solution in the solution browser about kafka

Write a solution on kafka with the knowledge that you earned by that task.

https://github.com/devonfw/solutions
https://devonfw.com/website/pages/solutions/

The solution should include:

• A short description on what problems Kafka can solve. Use links to reference existing documentation
• Automation scripts (helm charts) that can be used for setup
• Tracing setup description
• HealthCheck / Monitoring description

Do not cache json files

The architecture browser should prevent the browser from caching the json files.

Opentelemetry implementation for EKS

Only show finished solutions

As devonfw team, I want the user only to see finished solutions so that the architecture browser makes a good first impression.

There should be a parameter to activate/show the "Maturity level" filter so unfinished solutions can be shown for debugging/preview

Create preview images for the search results

As a user of the architecture browser, I want the images in the search results to be small so they can be loaded fast.

Opentelemetry implementation for AKS

Deploy grafana & jaeger with quarkus application using helm chart.

Include of solution snippets

As a solution writer, I want to move common snippets to separate files so I only have to maintain them once.

Solution hints:

• There should be a folder includes on top level
• The includes folder should contain a folder for each snippet
• The snippet folders should contain an asciidoc file and the file (e.g. images) used by this snippet
• Probably, one has to solve issues with https://github.com/devonfw/architectures/blob/master/scripts/fixImages.js
• (If a stack repo contains a solutions folder with an includes folder the includes folders should be merged)

Acceptance criteria:

• It is possible to include a snippet with images and linked files in a solution and the include is rendered correctly, the images are visible and the files are downloadable.

Kafka solution - further to dos

Further to dos #113:
Define Context and Scope more clearly
Solution Strategy
Tracing, Retry, and Kafka Health Monitoring
Limits (Constraints) and other existing alternatives to Kafka

shorten tool description

Organize structure in solution folder

Repo link: https://github.com/devonfw/architectures/tree/master/solutions 

Currently if you look at above like folders are not organized properly. For e.g authentication and authorization etc are lying around in this but nowhere it is associated with topic like security. To make it more organized we will rename current folders authentication to security_authentication, authorization to security_authorization etc.

Search parameter not appended in URL when there are no results

Expected behavior

As a visitor of the architecture browser, I expect the search parameter to be appended to the URL every time I perform a search.

Actual behavior

Search parameter is not appended to the URL when there are no results to show.

Steps to reproduce (bug) / Use Case of feature request (enhancement)

1. Visit the architecture browser at https://devonfw.com/website/pages/architectures/
2. Search for "auth"

Alternatives Kafka

23.6 (Open points from #545)

• Find existing alternatives to Kafka + Listing them + short description of them (focus, advantages, disadvantages) (2-3 sentences)

Add recommendations for authentication

Create new documentation in the solutions folder for authentication aspects/patterns.

Orientations:
https://github.com/devonfw-forge/devonfw-microservices/blob/main/documentation/access-control.asciidoc
https://github.com/devonfw/devon4j/blob/master/documentation/guide-access-control.asciidoc

Create generic template

Create generic template from output of issue#126 and issue#125

Incorrect options in the architecture browser

Expected behavior

As a user, I want to have correct options to filter the solutions so that I can see the solution which I want to know.

Actual behavior

Some options of architecture browser which currently do not have the solutions can be selected

Separate namespace of application and monitoring solutions

The namespaces of the application itself and the namespace of the tools for monitoring should be separated.

Provisioning Introduction appearing twice

Steps to reproduce.

open the link https://devonfw.com/website/pages/solutions/solution

click on Provisioning under Category.

On content pane, provisioning box appears twice. These are azure devops and github. It would be good, if the heading has azure devops or github actions.
Currently it looks duplicated.

Add manual for architecture browser

As a user, I want to know how I can contribute to the content of the architecture browser so that I do not have to find out by myself.

The architecture browser should link to this manual.

Availability in cloud

Create new documentation in the solutions folder for Availability

This can be divided into multiple smaller articles:

• Overview of Availability
• article for highly available architecture in AWS : architectural trade offs, best practices etc
• article for highly available architecture in Azure: architectural trade offs, best practices etc

Scaling in cloud

Create a new documentation for scaling in cloud.

It can be divided into multiple articles:

• Overview
• AWS scaling
• Azure Scaling
• IaC for AWS/Azure scaling

Refactor OpenTelemetry content to match the template

Istio solution - further to dos

Whats left from solution (Task #114)

Write out some topics in more detail

Create images and add them

Context and Scope

When to use our solution when not to use it

Add some more Code Fragments



Document our sample code

Security implementation for AKS open telemetry

Introduction to the solution browser

As a reader, I want to get the best consulting about cloud solutions so that devonfw is a good starting point for me, but if needing different solutions, I would like to get more information about the vendors.

The following section should be shown as an introduction above the solution browser:

Below you will find carefully harvested and proposed standard solutions of devonfw. Their central purpose is to standardize on green-field solutions as well as to foster discussion on why to do things differently. Broadening your knowledge about cloud reference architectures and further solution ideas, you might want to take a look at the
AWS Well-Architected Framework and its reference architectures as well as the Azure Well-Architected Framework and its reference architectures.

Add recommendations for communication between services

Create new documentation in the solutions folder for communication aspects/patterns between services.

Orientations:
https://github.com/devonfw-forge/devonfw-microservices/blob/main/documentation/communication.asciidoc
https://github.com/devonfw/devon4j/blob/master/documentation/guide-rest.asciidoc
https://github.com/devonfw/devon4j/blob/master/documentation/guide-kafka.asciidoc

Rename architectures browser to solution browser

Please rename the architectures browser to solution browser as we will show different solutions there and not only architectures.

Rework left Menu

As a website user, I want a clearly arranged menu so that I can find my way around the website.

Design: https://projects.invisionapp.com/d/main?origin=v7#/console/21750706/462361966/preview?scrollOffset=579.2000122070312

Acceptance criteria:

• only three level menu (1: Icons, 2: Arrow, 3: only text)
• fourth level on the right side (hide in mobile view)

Order tag values

The architecture browser should show the values of the tags in alphabetical order.

Architectures Search entries do not refresh on backspace

Expected behavior

As a user, I want to get actual results on whatever string I see in the search box so that I can remove characters if I mistyped one characters and can immediately see the results.

Actual behavior

Deleting a character does not refresh the architectures results at all

Steps to reproduce (bug) / Use Case of feature request (enhancement)

1. type "aci" -> see results
2. type additional "c" -> no results
3. remove additional "c" -> no change

Affected version:

• OS: Windows
• Browser: Firefox

Build failure due to rubygem issues in Solutions local settings

Add proxy server from below reference.
Settings file ./m2/settings-local-rubygem-proxy.xml needs to be copied.

https://github.com/devonfw/devonfw.github.io/blob/8799d571ef0d45736722974b34ab34d9570dd053/.github/workflows/build-and-deploy.yml#L35

Build should pass after adding the above configurations in github actions.

Documentation for backup in cloud

Create new documentation in the solutions folder for Backup.

This can be divided into multiple smaller articles:

• Overview of Backup
• AWS Backup: might want to consider services, best practices, challenges , any particular solution
• Azure Backup: might want to consider services, best practices, challenges , any particular solution

Harvesting istio integration from Zensus

Prometheus + Grafana (+ Opentelemetry?)

Talk to Tatjana and the istio experts from zensus about the integraton of istio in their monitoring setup.

Disaster Recovery in cloud

Create new documentation in the solutions folder for Disaster Recovery

This can be divided into multiple smaller articles:

• Overview of Disaster Recovery
• AWS Disaster Recovery : might want to consider services, best practices, challenges , any particular solution
• Azure Disaster Recovery: might want to consider services, best practices, challenges , any particular solution

Documentation for cloud storage

Create new documentation in the solutions folder for Cloud Storage.

This can be divided into multiple smaller articles:

• Overview of Cloud Storage
• AWS Cloud storage : might want to consider services, best practices, challenges , any particular solution
• Azure cloud Storage: might want to consider services, best practices, challenges , any particular solution
• IaC for AWS or Azure