Concrete Diagramming Fashions, a Light-weight Different to C4

2023-03-25 08:23:11

In cloud computing, if a useful resource has a URL in a developer dashboard or console, it’s most likely a concrete useful resource.

Concrete assets stand in distinction to summary assets. Summary assets are intangible and purely conceptual. Their very existence has an eye-of-the-beholder high quality to it. From computing, summary assets embody issues like companies and domains. We’ll see how an summary useful resource will be shaped from concrete assets later on this article.

Laying the muse

Making a concrete mannequin entails first defining concrete assets in a bottom-up method. These assets are the muse of the mannequin and the diagram(s) created from it. One creates a concrete mannequin by itemizing the concrete useful resource (see above for a listing of examples) within the system. When itemizing a useful resource, remember to embody its identify and kind (the form of factor it’s). Relying on the diagramming software used, these assets will also be given colours, icons, and different info. Concrete assets also can have baby assets. For (many) extra particulars on this course of, see this guide to multiperspective diagramming.

The next is an easy mannequin utilized in instance diagrams within the subsequent part:

Useful resource Title	Useful resource Kind	Coloration
getOrder	Lambda	Orange
createOrder	Lambda	Orange
getUser	Lambda	Orange
Orders	DynamoDB Desk	Blue
Order Historical past	DynamoDB Desk	Blue
Customers	DynamoDB Desk	Blue
Order	API Useful resource	Purple
Consumer	API Useful resource	Purple

Diagramming with concrete assets

Creating diagrams with concrete assets is simple. Relationships between concrete assets are designated with arrows like so:

A system diagram with concrete resources

Relations between these assets are designated by arrows

A number of diagrams will be created utilizing the mannequin. Here’s a sequence diagram displaying the steps of a fancy interplay between these identical assets:

A sequence diagram utilizing the identical assets

Toggling between these diagrams demonstrates they share a typical mannequin:

These two diagrams share widespread assets

Composing concrete assets

In diagramming, assets will be composed (put inside each other). This helps set up the diagram and offers the viewer helpful context. This diagram is similar because the sequence diagram within the earlier part, solely with composing assets:

The identical sequence as above, however with extra context

The newly-added composing assets are:

Useful resource Title	Useful resource Kind	Coloration
API Gateway	AWS Service	Purple
Lambda	AWS Service	Orange
DynamoDB	AWS Service	Blue
Amazon Net Companies	Cloud Supplier	Orange

The addition of 4 composing assets provides the diagram extra order. The viewer can be given necessary context about this method, particularly the cloud supplier (Amazon Net Companies) and the companies in that supplier it makes use of (API Gateway, Lambda, and DynamoDB).

Moreover, these compositions can simplify a diagram. By zooming out and displaying the one composing assets, higher-level interactions are revealed:

Simplifying a sequence diagram utilizing composing assets

Because the above instance demonstrates, any quantity of composition is feasible. Every “stage” of element makes the diagram less complicated till solely the highest-level info is seen. On this instance, on the very highest stage, the interplay is between solely the consumer and AWS.

Up to now in these diagrams, each useful resource, even on the highest ranges, is a concrete useful resource. API Gateway, Lambda, DynamoDB are all actual companies, as are the person assets (tables, Lambda, and many others.) in them. Generally, although, it’s useful to indicate assets composed in ways in which aren’t strictly literal. That is achieved utilizing summary assets.

(Non-obligatory) Including summary assets

Concrete assets are the muse of concrete fashions. Summary assets play a secondary, and elective, half.

As famous beforehand, summary assets are intangible and purely conceptual. For diagramming functions, they exist solely as compositions of many concrete assets. In contrast to concrete assets, summary assets don’t convey info per-se. Their worth is of their skill to prepare and simplify in conceptual methods.

Think about the sequence diagram within the earlier part. It separates the database tables, Lambdas, and APIs into their respective AWS companies. That is extremely related, however not the one solution to set up them. Somtimes (maybe typically) it’s higher to current them as companies, like within the following diagram:

The identical sequence as above, however with summary assets (Companies, in inexperienced) as context

All the interactions (arrows) are the identical as earlier than. Order Service and Consumer Service (rendered in inexperienced) are the summary assets. These companies exist solely conceptually; they’re nothing greater than a handy means of grouping APIs, Lambdas and database tables. Like concrete assets within the earlier part, they can be utilized to exhibit higher-level relations and interactions:

Simplifying a sequence diagram with summary assets (Companies, in inexperienced)

The underside-up, just-the-facts philosophy of concrete modeling gives necessary advantages. It helps preserve diagrams grounded in actuality. Imprecise and unfaithful info is less complicated to identify, and will be rooted out sooner.

Concrete fashions don’t depend on externally-prescribed abstractions or ideas. These fashions are tailored to a system, not the opposite means round. They describe techniques as they’re utilizing the langauge of the techniques themselves.

As talked about, concrete diagramming fashions are perfect for creating diagrams with plenty of element. This makes them excellent for creating system documentation that delivers long-term worth.

Concrete diagram modeling is a substitute for, however not a substitute of, the C4 Model created by Simon Brown.

What’s C4?

Brown introduces the C4 Mannequin as “an ‘abstraction-first’ method to diagramming software program structure.” It prescribes “a set of hierarchical abstractions and a set of corresponding hierarchical diagrams.” These 4 prescribed ranges of abstraction are Context, Container, Part, Code (therefore C4).

The hyperlink above describes these abstractions and offers examples for every (“Within the C4 mannequin, a container represents an utility or an information retailer”. Examples of “containers” in C4 embody “Cell apps”, “Databases”, and “File techniques”). When modeling with C4, the modeler is meant to map their very own assets to one among these 4 abstractions.

The C4 mannequin can be top-down; it means that Context diagrams (the best stage) is an efficient place to begin for diagramming because it permits the viewer to see the large image.

Shortcomings of the C4 Mannequin

The C4 Mannequin is pretty properly established, nevertheless it does have some shortcomings:

Overly-prescriptive abstractions

One among C4’s objectives is to create a “ubiquitous language” to explain software program techniques. Diagram authors are tasked with mapping all of their assets to one among 4 ranges of abstraction (Context, Container, Part, Code), after which use them in a handful of (additionally prescribed) diagram varieties. The pondering is that there’s long-term profit to the business through the use of a typical language for abstraction in software program diagramming.

The issue is that techniques as we speak have many various sorts of issues. Servers, databases, virtualized containers, APIs, pipelines, repositories, packages, libraries, and (many, many) cloud assets are all actual, concrete issues that present actual worth. Forcing them into one among C4’s 4 ranges of abstraction doesn’t actually accomplish a lot. A database is a database; debating whether or not it’s also a Container or a Part simply isn’t worthwhile. Diagram authors and viewers are higher off seeing these assets for what they really are.

Additional, when abstraction known as for, utilizing domain-specific abstractions makes extra sense than utilizing arbitrary ones. Diagram authors profit from desirous about every system by itself phrases (and in its personal phrases). Diagram viewers do, too.

Abstraction blindness

Even once they’re a very good match, over-using abstractions can do hurt. The highest-down, abstraction-first method of C4 dangers focusing an excessive amount of on a system’s abstractions on the expense of its concrete assets.

A system’s concrete assets, the precise issues in a system, are virtually all the time extra necessary than the abstractions used to simplify them. So are the real-world relations and interactions between them. These are the assets diagram viewers most want to grasp. Diagrams, and diagramming fashions, ought to concentrate on them as properly. Solely after doing the “exhausting” work of detailing these real-world assets ought to an creator take the freedom of abstracting them away.

Concrete fashions and C4 Fashions

Each concrete fashions and C4 fashions have their place. They share the identical objectives of group, consistency, and reuse in technical diagrams. C4 is top-down, prescriptive, and abstraction-first. Concrete fashions are bottom-up, a lot much less prescriptive, and concrete-first. Which to decide on is dependent upon one’s private choice and diagramming objectives.

Mannequin-based diagramming is sort of all the time the proper selection when creating diagrams with long-term worth. Concrete diagramming fashions lean into this by emphasizing the actual, value-producing assets in system diagrams. They’re a superb selection when the purpose is to actually inform the viewer, slightly than merely make an impression.