Consuming wine in my family during a quarantine period has increased significantly. So we are wine experts all of a sudden. “Its flavor is evocative of prunes and apricot.” “I can smell a hay.” Hay, aha!

Anyway, a few days ago, I was taken by a wine shop ad. The banner mouthing off that they offer up to 50% on Israeli wine and free home delivery. The catch is that to receive the discount, you should become their club member, of course.

I couldn’t resist. Day after, on my official holiday, the wine courier woke me up. Hello, weekend! I give a perfect score for a shopping experience. The banner was attractive, the process was easy and intuitive, the delivery was fast, the wine was tasty (and smelled hay!).

Well, the subject of this article is Package Diagrams. Let’s take a look at the online wine shopping process through the Packages prism.

Package Diagram

Package diagrams are structural diagrams used to show the organization and arrangement of various model elements in packages. The Packages are logical containers that group together related elements of the software (such as a shipped package that groups wines of various wineries).

These elements can be related based on data, behavior, or any other logical crap. The Package diagram has the same idea as folders on your computer; it allows orientation in the large model. If you are looking for some documents, I’ll give you a hint, Sherlock — probably you can find it in the “documents” folder.

Same here, think about the brilliant banner of a wine shop. It can be a part of the Advertisement package. Can you see my point?

Package diagrams show packages and the dependencies between them. So, the makeup of a package diagram is relatively simple. Each diagram includes only two symbols: package and dependency.

Packages

Simple Package

I’ll continue with an advertisement example.

A simple package, aka basic package, has a depiction that looks like a tabbed folder (surprised?). A package is a namespace for the elements it contains. In a simple package, the name goes within the folder, in the center.

In this case, a package is named Advertising Campaign. It can organize the named elements of software into a separate scope. The simple package’s purpose is to show that this package exists, lives, and is used in that diagram.

When details are needed, for example, you want to show different Advertising Campaign components, nest the elements within the folder just like this:

Take a look at this diagram. The package is still represented by what looks like a file folder, but the name was moved to the tab at the top if you notice.

I fall on a banner. But, obviously, by becoming a club member, I subscribed to the mailing as well (“mark the checkbox if you want a heads up”). So, this Advertising Campaign package, the way I see it, can include different components to achieve the goal. I listed here Banner, Instagram, and Gmail Ads components.

Well, it’s important to understand that packages can contain one or more elements of different types. They are only logical representations, or logical grouping, of things within our diagram. A package can contain classes, interfaces, components, or other diagrams. We can even have packages that get nested.

Nested Packages

I tapped the banner and was redirected to the Wine shop website (which can be represented as a package itself, right?). As I mentioned before, to receive all the cream of this campaign, I should join Wine Lovers’ secret society. In other words, to become a club member. Now, in my vision, it means that some Club Member Service is a part of Customer Service. I mean, it can be represented as a package within the package:

In reality, you can nest packages as deep as you want. However, in diagrams, try to keep it as clean as possible. Don’t nest packages more than maybe two or three deep. You need to understand that each package defines a scope.

Each element can be uniquely identified in the system by a fully qualified name, based on its own name and the package’s name. It means that nested elements’ names must be unique within the package.

For illustrative purposes, I will add the Member Card component to the nested package. The same component that manages membership expiration, for instance.

If you want to reference the Member Card element in the documentation, you need to use its fully qualified name by the double colon between parts of CustomerService::ClubMember::MemberCard.

Dependencies

Are we cool? Now, get just a little bit complicated. In part, package diagrams are used to describe import and access dependencies between various packages and elements within your system.

A package can import an individual element from another package. A package can import the entire contents of other packages. Finally, packages can be merged. It is important to denote the relationships among different packages and elements appropriately.

Element Import

Element import it’s a directed relationship between an importing namespace and an imported packageable element.

Let’s assume my apartment is a package. The wine shop is another package. Now, by placing an order, I don’t want to import a wine shop into my apartment, just it’s content. Kidding. I want to import selected wine bottles (element).

All dependencies within the Package diagram notated as a dashed line with an open arrow. The import tag says that import is public. Pardon? Not that I’m greedy, but hands off my wine.

Guess what? The hottest Restaurant imports the wine from the wine shop as well. So the wine is visible for further import through the Restaurant.

Meanwhile, wine imported into my apartment is private, and visible only by elements within Gene’s Apartment (spouse, cat, friends…) and not further outside. The access tag to prove it.

Package Import

This is exactly the case when you want to bring whole wine shop content into your apartment 🍷 Here is a more realistic example:

This diagram is an example of how you would show a package importing another package. The Payment Service package is doing a public import of the Customer Service and a private import of the Shopping Cart packages.

Package Merge

The package merge is a direct relationship in which one package’s contents are extended by another package’s contents. The contents of the two packages are ultimately combined to create a new package. This is a kind of generalization that allows you to provide different definitions of the same concept.

Take a look at the diagram above. Wine Search, Featured Wine, Weekend Sale, and Shopping Cart packages define a specific functionality. However, the content of all these packages can be merged into a Wine Shop Website package.

We are done. Now, let’s check the completed overall view of the basic Package Diagram.

Looking good? Looking good! Chin-chin!