How should Detailed architectures work when one architecture references another?

[Budlee]

Support Question

We have been looking at the detailed-architecture filed that exists in the node as we want to combine two patterns together.
The question is how should the detailed-architecture value work?

The detailed-architecture should reference another calm specification, however, I am unsure what this does to the node that references the detailed architecture.
I have created a PR alongside this so that it highlights the issue further

• Patterns
  • p-api-gateway.json
  • p-two-tier-api-producer.json
• Generated instantiations
  • i-api-gateway.json
  • i-two-tier-api-producer.json

Lets take the instantiated api-gateway-producer in the i-api-gateway.json (lines 24-37):

{
      "unique-id": "api-producer",
      "node-type": "system",
      "name": "API Producer",
      "description": "The API Producer serving content",
      "detailed-architecture": "{{ DETAILED_ARCHITECTURE }}",
      "interfaces": [
        {
          "unique-id": "producer-ingress",
          "host": "{{ HOST }}",
          "port": -1
        }
      ]
}

The question I have is if the interfaces should be defined in the i-api-gateway.json?
This information is going to be in the i-two-tier-api-producer.json, does this mean that interface information should be duplicated in both the architectures?

This question also has a bearing on the relationships as in i-api-gateway.json the interface is defined against its unique-id

{
      "unique-id": "api-gateway-api-producer",
      "relationship-type": {
        "connects": {
          "source": {
            "node": "api-gateway"
          },
          "destination": {
            "node": "api-producer",
            "interfaces": [
              "producer-ingress"
            ]
          }
        }
      }
    }

I think this question has two answers:

• interface information is duplicated in the places you need it, in my case the i-api-gateway.json and i-two-tier-api-producer.json.
  • This does mean the tooling will need to validate that the interface information is exactly the same
• interface information is not duplicated
  • This means the tooling will need to be enhanced to understand and "know" the other downstream architecture ids

Other pieces I thought about for detailed-architecture references are:

• if you specify a detailed-architecture should it only be a system? Does it make sense to specify a detailed-architecture value on a node-type of db?
• In order to parse detailed architectures do we need to construct a graph out of the interconnectivity and references? A library that can use this would make parsing easier

[Budlee]

Detailed architecture PR for this discussion: #795

[LeighFinegold]

@Budlee - on #650, @rocketstack-matt and I discussed how detailed architecture would be used in relating to referencing other nodes in systems etc. Technically a relationship that spans both systems would be at higher level.

[Budlee]

@LeighFinegold, does this mean to combine patterns together they need to be defined in a top level eco-system and this is what maps the relationships?

If this is the case then tooling will need to pull out the ids in the ecosystem relationships and check the ids exist in the each of the individual documents of the systems.

I did miss #650 so maybe this ship has sailed but is it not better that the tooling supports the ability to reference other documents opposed to having to have a layered approach like C4 does.

[LeighFinegold]

I don't think the decision is set in stone. We were discussing from the angle of documenting architectures.

Let's discuss on the #796

[jpgough-ms]

Is #817 a solution to this issue?