Pros and cons of Includes vs Extends for Independent Stream-Aligned Teams?

[andrewharmellaw]

A set of stream-aligned teams are going to start using C4/Structurizr. We want them to be able to define their model elements effectively without being crushed by the cognitive (over)load of one single shared file.

I think we will have a top-level dsl file that is defining the shared elements (e.g. the cross-everyone personas, shared libraries, and abstract patterns) and then each stream-aligned team will have their own dsl files that either are included into this, or extend it. Teams will consume the services of other teams to deliver the overal client experience.

What are the pros and cons of each approach? Incudes vs extends.

[simonbrowndotje]

It's hard to say without more information to be honest, but I'd first recommend taking a step back to understand how you want to model all of this using C4 independently of tooling (i.e. sketch some diagrams on a whiteboard) ... much of the answer depends on what you mean by "services", whether the stream-aligned teams are creating new C4 software systems, modifying existing C4 software systems, or both.

[andrewharmellaw]

Great question. The "services" (which will map to softwareSystem are pretty fixed and don't change a lot. The cross-team collabs ought to happen at this level too. When it breaks then its going to mean cross-team collab anyway. One thought I have however is, if a team wants to represent a lower-level, cross-team interaction (i.e. their container or component calls an API on something managed by another team, they'll want to represent that. And the hope is we can use dynamic diagrams to show come of the key cross-team journeys, I guess at multiple levels. And deployment diagrams too that will want to show lower-level comms between containers/components.

[andrewharmellaw]

It seems like the biggest differentiator for us is that if teams use includes then they can all see the elements in the other team's included files (because there is only a single workspace. Using extends means that any elements you add in an extension workspace are not visible to the extension workspaces of other teams.

For us this is the deal breaker - we want to know where and at quite low levels of detail the relationships (and dependencies) between the teams (so we can start thinking about it more closely).

[simonbrowndotje]

we want to know where and at quite low levels of detail the relationships (and dependencies) between the teams

As I mention in my "C4 model misconceptions" talk, I don't recommend doing this because (1) it's a form of coupling and (2) it perhaps suggests the team boundaries are incorrect/suboptimal. Enterprise usage - part 2 (free to read; requires an account) summarises the problems you will likely run into when using !include at scale.

[andrewharmellaw]

Thanks Simon, this is great. I'll have a look. 🙏🏻