Adding software architecture models to jQA

[Michael Hunger]

Good one from Simon https://www.youtube.com/watch?v=m76bR16EhrU

With a honorary mention of jQA

When he mentioned that tools like jQA have no underlying model, what he means is no model on the higher level.

I think it would be really good to add higher level architecture models to jQA

Which could be populated from different sources

- manually

- plantuml

- c4/structurizr API (system, container, component, class)

- other modeling tools

- inferred via graph algorithms / queries / projections

What do you think and what should be the modeling elements?

I.e. the "ubiquitous language" of software architects.

What do you think?

Michael

[Gerd Aschemann]

I consider this a very good idea. 

We already are doing some software architecture modeling based on the mentioning tools and evaluate our code by means of jQA. But I see a need to unify the approaches, and to find a common vocabulary and concepts in a higher level abstraction. Additionally it should become more convenient for a user (i.e., architect) to make use of the tool and the abstraction.

I have left my last project with architecture modeling and evaluation based on the samples provided by Jens, and the discussions with Dirk. But I fear that in general it is hardly understandable (and to much boilerplate cypher coding around the underlying concepts) for the remaining developers to maintain it in the long run.

I hope to be able to participate in upcoming efforts since I am about to introduce jQA for software/architecture quality assurance in my currently starting new project.

Cheers

  Gerd

--
You received this message because you are subscribed to the Google Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.
To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.
To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuWmJQFGEn0%3DF6cOfBCnspKrs6njF1a9LgEZm3Rq%2BHGjyFg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

Gerd Aschemann --- Veröffentlichen heißt Verändern (Carmen Thomas)
+49/173/3264070 -- ge...@aschemann.net -- http://www.aschemann.net

[Dirk Mahler]

Hi,

watched the talk on my way to the csutomer's office in the morning: he
has some very good points in it but I think that jQA is not so far away
from what he's talking about. The "concept"s are the tool for creating a
model on top of the code, see this example from XO:


MATCH
(frameworkComponent:Main:Artifact)
WHERE
frameworkComponent.name in [
"xo.api",
"xo.spi",
"xo.impl"
]
SET
frameworkComponent:Framework:Component
RETURN
frameworkComponent

What I see is that we need

- a better notation (e.g. PlantUML)
- and patterns or pre-defined templates on how model elements (e.g.
components from C4) are mapped to code (i.e. packages or artifacts).

PlantUML support for concepts has already been discussed and it's in the
pipeline. But nevertheless let's collect ideas!

Cheers,

Dirk

>> [1].

>> For more options, visit https://groups.google.com/d/optout.
>
> --
> Gerd Aschemann --- Veröffentlichen heißt Verändern (Carmen Thomas)
> +49/173/3264070 -- ge...@aschemann.net -- http://www.aschemann.net
>

> --
> You received this message because you are subscribed to the Google
> Groups "jQAssistant" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to jqassistant...@googlegroups.com.
> To post to this group, send email to jqass...@googlegroups.com.
> Visit this group at https://groups.google.com/group/jqassistant.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/jqassistant/F803FDB2-9BDF-42A8-962E-63F664456E79%40aschemann.net
> [2].

> For more options, visit https://groups.google.com/d/optout.
>
>

> Links:
> ------
> [1]
> https://groups.google.com/d/msgid/jqassistant/CAKZwuWmJQFGEn0%3DF6cOfBCnspKrs6njF1a9LgEZm3Rq%2BHGjyFg%40mail.gmail.com?utm_medium=email&utm_source=footer
> [2]
> https://groups.google.com/d/msgid/jqassistant/F803FDB2-9BDF-42A8-962E-63F664456E79%40aschemann.net?utm_medium=email&utm_source=footer

--
Dirk Mahler
Senior Consultant IT
buschmais GbR

-----------------------------------------------------------------
Inhaber Torsten Busch, Frank Schwarz, Dirk Mahler, Tobias Israel
Adresse buschmais GbR, Leipziger Straße 93, 01127 Dresden
Telefon +49 (0) 351 3209 23-0
Fax +49 (0) 351 3209 23-29
Mobil +49 (0) 177 3137411
E-Mail dirk....@buschmais.com
Internet http://www.buschmais.de
-----------------------------------------------------------------

Diese E-Mail enthält vertrauliche undoder rechtlich geschützte
Informationen. Wenn Sie diese E-Mail irrtümlich erhalten haben,
bitten wir Sie diese E-Mail umgehend zu löschen. Das unerlaubte
Kopieren sowie die unbefugte Weitergabe dieser E-Mail ist nicht
gestattet.

This e-mail may contain confidential or privileged information. If
you are not the intended recipient we kindly request you to delete
this e-mail immediately. Any unauthorized copying, disclosure or
distribution of the material in this e-mail is strictly forbidden.

[Jens Nerche]

Hi folks,
I think my approach using arc42, Asciidoc and PlantUML is going in that direction. I see it as a start, not the end.
So the "users" dont need to touch cypher for the basic stuff. But the Cypher I provided uses the imported stuff directly,
not meta model. As I understand Michael is just suggesting to create a meta model or schema or "ubiquitous language".
Then we would be able to import from different sources an use the same Cypher queries to check the implemetation
against the model. And decouple the checks from the documentation style.

Best regards,
Jens

[Michael Hunger]

I started to add support for structurizr a few years back but didn't finish it :( (bad Michael), but I got quite far.

The project would have to be updated for the latest versions of structurizr, jqassistant and XO (I just tried it but I'm struggling)

There were also open questions on what to map the "architecture language to".

https://github.com/jqassistant-contrib/structurizr-plugin

Docs: https://github.com/jqassistant-contrib/structurizr-plugin/blob/master/src/main/asciidoc/structurizr.adoc

Michael

send an email to jqassistant+unsubscribe@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.
To view this discussion on the web visit

https://groups.google.com/d/msgid/jqassistant/CAKZwuWmJQFGEn0%3DF6cOfBCnspKrs6njF1a9LgEZm3Rq%2BHGjyFg%40mail.gmail.com

[1].
For more options, visit https://groups.google.com/d/optout.

--
Gerd Aschemann --- Veröffentlichen heißt Verändern (Carmen Thomas)
+49/173/3264070 -- ge...@aschemann.net -- http://www.aschemann.net

 --
You received this message because you are subscribed to the Google
Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send

an email to jqassistant+unsubscribe@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "jQAssistant" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant+unsubscribe@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/14b22bfdad37c8dd70c320b7dba99db0%40buschmais.com.

[Michael Hunger]

As I understand Michael is just suggesting to create a meta model or schema or "ubiquitous language".

Then we would be able to import from different sources an use the same Cypher queries to check the implementation 

against the model. And decouple the checks from the documentation style.

Yes exactly.

Add explicit support for the / a architecture language and connect it to the live code.

If the architecture description is then coming from manual creation / a DSL / another tool / diagrams doesn't matter.

But it would be good to compare / match it to the architecture we can derive from the code.

And the deployment / container aspects can (hopefully) be related to the work around microservice/container management/monitoring that's also in the works.

The (docker) container deployment bit could probably something for Bernd?

Michael

--

You received this message because you are subscribed to the Google Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant+unsubscribe@googlegroups.com.
To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/fc621e58-0412-4cd6-8026-bfb7630f4b47%40googlegroups.com.

[Michael Hunger]

Oh wow, that was from March 2015, bad, bad Michael.

Ok, I sat down and did the version upgrade dance, if you want to have a look or give it a try:

It's probably still not fully functional yet (haven't looked into jQA plugins for a while), but would be good to try with the spring-petclinic example from Simon and align with our own PetClinic.

My main discussion points would be:

* naming

* where we join together the JQA-Model (java/spring) with the structurizr model (e.g. type (==FQN) in component or code-element9

* which aspects are we missing

* how to add those dynamic relationships from structurizr to JQA which is more static

https://github.com/jqassistant-contrib/structurizr-plugin

* jQAssistant 1.3.0
* XO 0.8.1
* Neo4j 3.1.3
* structurizr 1.0.0-RC3

@Dirk I ran into one issue with the upgrade where I had to add useless @Label annotations even on helper interfaces that only held a few property methods.

Michael

[Oliver B. Fischer]

Hi,

the great advantage of jQA is that is not opinionated. It gives me the ability to use it as I need it. I can analyse everything and put in a relation to another pice of something. 

Not having a underlying model is a great advantage because I am not limited to someones else view on software architecture. I am not forced to work with or against a from my perspective limited model.

BTW, what could be a model (ubiquitous language)? Such a model/language must be so expressive  what you can describe each system. If you meet two architects, you will have three definitions of the same thing.

Oliver

Am 13.10.17 um 02:17 schrieb 'Michael Hunger' via jQAssistant:

--
You received this message because you are subscribed to the Google Groups "jQAssistant" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuWmJQFGEn0%3DF6cOfBCnspKrs6njF1a9LgEZm3Rq%2BHGjyFg%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

-- 
N Oliver B. Fischer
A Schönhauser Allee 64, 10437 Berlin, Deutschland/Germany
P +49 30 44793251
M +49 178 7903538 
E o.b.f...@swe-blog.net 
S oliver.b.fischer
J oliver.b...@jabber.org
X http://xing.to/obf

[Dirk Mahler]

Hi Micha,

thanks for the efforts! Can you give a me pointer to the labels you needed to add? Will have a look at it.

Cheers

Dirk

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuWmdgDioN8sKmm9WckS3qzz8Fe5DqbArVucdDvFr0DJrBA%40mail.gmail.com.

[Dirk Mahler]

Hi,

getting the point a bit clearer now but I see the danger to create another inflexible framework which is highly opinionated. 

What Simon describes in his talk is that developers shall define their ubiquitous language and gives them C4 as a template. Creating rules or reports on top of that is the easy point, here jQA can provide notations for PlantUML, Asciidoc etc. 

But there's a part below that which is mentioned by Simon as well and this one is essential: how do these language elements actually map to the code? This is something very individual: For definining elements that would map to components in the style of C4 I've used at least two different approaches in different flavours in my projects over the years:

- Packages and their contained sub-packages

- Artifacts (e.g. Maven-Modules) or groups of them

Furthermore components described by these code elements not necessarly were identified by their name, I've even used patterns for that if I knew the general structure (which has been enforced by jQA).

So I see two parts: 

1. The abstract one where jQA and it's plugins can provide support using different notations out-of-the-box using elements of the language (i.e. Container, Compoments or Class)

2. The concret one where a team/architect/developer needs to define its own individual mappings

The second usually is much more challenging, it means defining code structures that can be mapped and writing the required concepts. I remember one of the last questions by Gerd here on the mailing list, it was exactly about it. And Michaels last mail about the structurizr plugin asked the same thing: "* where we join together the JQA-Model (java/spring) with the structurizr model (e.g. type (==FQN) in component or code-element"

This is where I see templates, i.e. concrete code structures (e.g Maven-Modules, packages etc.) and the jQA mappings to C4 (or whatever language we promote).

Any opinions?

Cheers

Dirk

BTW: I think that going for C4 would have the advantage that Simon might pickup jQA a bit deeper in his talks ;-)

------ Originalnachricht ------

Von: "'Michael Hunger' via jQAssistant" <jqass...@googlegroups.com>

An: "jqass...@googlegroups.com" <jqass...@googlegroups.com>

Gesendet: 13.10.2017 21:45:39

Betreff: Re: [jQAssistant] Re: Adding software architecture models to jQA

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuW%3DzEW9w2FWr31%2B2q70Z0rwFAg06%2B%2B1TZ0gW80v8m5rk9A%40mail.gmail.com.

[Dirk Mahler]

Hi,

had a walk in the park (great sunny weather today!!!) and the following idea came into my mind: We can provide a "jqassistant-c4-java-plugin" that consists of pre-defined rules for supporting the C4 model (i.e. containers, components and classes):

Component:

 - Graphical Report about component dependencies

 - Verification of defined component dependencies

 - Report about ports and adapters of each component (i.e. classes of a component that are used by other components or using classes of other components)

Container 

 - Report about containers and their contained components

 - Report about (static) dependencies between containers

- Report about components between containers

The trick would be that these rules depend on rules that the user must provide and which represent the mapping of the code-structures to these elements, e.g. in Cypher:

[[c4-java:Component]]

[source,cypher,role=concept]

.Defines the components

----

MATCH

  (component:Package)

WHERE

  component.fqn in ["com.acme.cart","com.acme.order","com.acme.payment"]

SET

  component:C4:Component

RETURN

  component

---- 

[[c4-java:DefinedComponentDependency]]

[source,cypher,role=concept]

.Defines the components

----

MATCH

  (cart:C4:Component{name:"cart"}),

  (order:C4:Component{name:"order"}),

  (payment:C4:Component{name:"order"})

CREATE UNIQUE

  (order)-[o1:DEFINES_DEPENDENCY]->(payment),

  (cart)-[c1:DEFINES_DEPENDENCY]->(order)

RETURN

  *

---- 

And similar for containers: 

[[c4-java:Container]]

[source,cypher,role=concept]

.Defines the containers

----

MATCH

  (:Maven:Project)-[:CREATES]->(container:Artifact)

WHERE

  container.type in ["ear","war"]

SET

  container:C4:Container

RETURN

  container

---- 

Note that these concepts could also easily be provided by the structurizr plugin or other notations (asciidoc tables, plantuml) etc.

Opinions?

Cheers,

Dirk

------ Originalnachricht ------

Von: "Dirk Mahler" <dirk....@buschmais.com>

An: jqass...@googlegroups.com

Gesendet: 14.10.2017 12:25:45

Betreff: Re[2]: [jQAssistant] Re: Adding software architecture models to jQA

[Jens Nerche]

Hm, I thought we speak the whole time about such things: plugins that provide Concepts and Constraints using Lables in some Ubiquitous Language, e.g C4. Thats why I did not understand why that would limit the users or jQA in any way. The opposite is the case: they may use some wide spread models/language elements/architactural patterns without the need to write the Cypher by themselfs. More can be done with simple configurations or declarations.

Ok, the mapping of the actual project code to these labels have to be done by the user. But given that the famous 80% of projects do use some kind of Convention over Configuration setup, we could also provide some plugins that do the mapping for the most usual cases.

Jens

P.S. btw you can close the model-code-gap only with DSLs and Language Workbenches... ;)

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuW%3DzEW9w2FWr31%2B2q70Z0rwFAg06%2B%2B1TZ0gW80v8m5rk9A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "jQAssistant" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jqassistant/w4F1oyGKXJ8/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jqassistant+unsubscribe@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/em7c655c3e-4560-4327-9025-5cb147b293ed%40mythenmetz.

[Dirk Mahler]

Hi,

Hm, I thought we speak the whole time about such things: plugins that provide Concepts and Constraints using Lables in some Ubiquitous Language, e.g C4. Thats why I did not understand why that would limit the users or jQA in any way. The opposite is the case: they may use some wide spread models/language elements/architactural patterns without the need to write the Cypher by themselfs. More can be done with simple configurations or declarations.

In the projects I've worked in the same terms were often used with very, very different meanings: module, component, even layers, etc.. That makes it so difficult to define common concepts for them. Even in the C4 model I didn't see a definition for infrastructure code (common/core/shared/util, you know), very likely it needs to be modeled as a component. 

Ok, the mapping of the actual project code to these labels have to be done by the user. But given that the famous 80% of projects do use some kind of Convention over Configuration setup, we could also provide some plugins that do the mapping for the most usual cases.

Seems I've been thrown into the other 20% so far... ;-) Do you have concrete examples? AFAIK Spring Boot gives you everything up to the top level package for your app, the rest is up to you.

P.S. btw you can close the model-code-gap only with DSLs and Language Workbenches... ;)

...and/or jQA. It's generating from a model or validating against a model.

But nevertheless: do you think the proposal could work?

Cheers,

Dirk

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CA%2BLGUUxYHyPV1u-9OxCRSBX5B3bs_-MqyPcQMu8O8pQ%2B5VG-YA%40mail.gmail.com.

[Michael Hunger]

Yes, that was my thinking too. 

Not to build something fixed/opinionated into jQA, 

but offer the means of choosing one of the languages as a plugin or doing your own and then,

like Dirk showed it with the C4 plugin allow the users to put in their own concepts/language.

Of course with a number of sensible and working examples. 

So those plugins would provide/use the terms (aka connection points) from these models.

And then having (optional) plugins that connect to those systems/notations to make it easier for people to integrate them into the/their jQA model.

I think the important aspect is to highlight that it is about finding and making explicit their (architectural) language that makes sense for each project.

When I told people so far, that we see the higher level concepts you derive/apply to your raw results represent the vocabulary of your own language which then allows you to formulate concepts, constraints and reports in terms of that language (and not class, field, method, package), then most had a great aha-moment and found it super useful.

Cheers, Michael

PS: Some ideas we can learn/steal/use from C4 are:

- components offer public interfaces and hide their own parts

- containers as deployment units (beyond Java) that can also be monitored

- run graph algorithms / clustering on top of our data at different granularities / 

- making more use of generated higher level graph visualizations for exploration (graphviz, d3, yFiles), e.g. as part of reports

- this I would reuse by sending data from jQA to structurizr: generating presentations, pdfs, etc from the architecture

Hi,

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CA%2BLGUUxYHyPV1u-9OxCRSBX5B3bs_-MqyPcQMu8O8pQ%2B5VG-YA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "jQAssistant" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant+unsubscribe@googlegroups.com.
To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/em852f3a2e-fc06-4c57-bd52-02d49a3cd80b%40mythenmetz.

[Dirk Mahler]

Hi,

I've created a prototype of a "C4 Java" plugin, you can find it here: https://github.com/jqassistant-contrib/jqassistant-c4-java-plugin.

From a user perspective he would need to create the concepts in https://github.com/jqassistant-contrib/jqassistant-c4-java-plugin/blob/master/src/test/resources/META-INF/jqassistant-rules/c4-java-test.xml, definitions of components and allowed dependencies. He then would be able to use the concepts and constraints defined in https://github.com/jqassistant-contrib/jqassistant-c4-java-plugin/blob/master/src/main/resources/META-INF/jqassistant-rules/c4-java.xml, e.g.

Constraint:

"c4-java:UndefinedComponentDependency":  Detects undefined dependencies between components and reports the types that create the problem

Report:

"c4-java:ComponentDependency.graphml": GraphML-Report of component dependencies:

IMHO looks quite nice so far. Needs to be extended by some more reports and groups for easier execution, of course some documentation needs to be written.

Cheers,

Dirk

------ Originalnachricht ------

Von: "'Michael Hunger' via jQAssistant" <jqass...@googlegroups.com>

An: "jqass...@googlegroups.com" <jqass...@googlegroups.com>

Gesendet: 15.10.2017 20:17:46

Betreff: Re: Re[5]: [jQAssistant] Re: Adding software architecture models to jQA

To unsubscribe from this group and stop receiving emails from it, send an email to jqassistant...@googlegroups.com.

To post to this group, send email to jqass...@googlegroups.com.
Visit this group at https://groups.google.com/group/jqassistant.

To view this discussion on the web visit https://groups.google.com/d/msgid/jqassistant/CAKZwuWmDnQq5LSAz93MrLj%3D%3DLCBpr11PCFSN5znZHr5q_rTF%3DQ%40mail.gmail.com.