Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท Deployment and Packaging

Package Diagrams and Dependencies

Learn UML package diagrams: packages, visibility, import and access dependencies, layered architecture and metrics for coupling, with runnable Python.

Once a model has more than a few dozen elements, you need a way to organize it. A package is a namespace that groups related model elements: classes, interfaces, use cases, even other packages. A package diagram shows those groups and how they depend on each other. It is the model-level counterpart of folders, Java packages, Python modules or C# namespaces.

Package diagrams are cheap to draw and very good at revealing structural problems: layers that are skipped, cycles, and a "util" package everything leans on.

Notation

A package looks like a folder: a rectangle with a small tab on top-left. Its name sits in the tab or in the body. Elements inside it have qualified names such as shop::orders::Order.

Relationships between packages are all dashed arrows with different keywords:

Relationship Keyword Meaning
Dependency none A uses something in B; a change in B may break A
Import <<import>> The public names of B become visible in A's namespace
Access <<access>> A may use B's public elements but they are not added to A's namespace
Merge <<merge>> A extends B by merging B's content into it (used in metamodels)

Visibility of an element inside a package: + public, - private. Only public elements can be imported or accessed from the outside. Therefore a package can hide its internals like a class does.

flowchart TB
    subgraph app["shop"]
        UI["ui"]
        SVC["services"]
        DOM["domain"]
        DATA["persistence"]
    end
    UI -.->|"uses"| SVC
    SVC -.->|"uses"| DOM
    SVC -.->|"uses"| DATA
    DATA -.->|"uses"| DOM

A layered arrangement: dependencies run downward, and the domain depends on nothing.

Layered architecture and the rules

Packages are the natural way to express layers. A classic arrangement is presentation, application services, domain, and persistence/infrastructure. A few rules keep layers meaningful:

  1. Dependencies point one way, usually downward or inward. A lower layer must not know about an upper one.
  2. No cycles between packages. If ui depends on services and services on ui, the layers are fiction.
  3. Do not skip layers without a reason (a strict layering says a layer only uses the one right below).
  4. Put the stable core in the middle: with dependency inversion the domain defines interfaces and the persistence layer implements them, so the arrow points from persistence to domain.

The last rule is the heart of "clean" or "hexagonal" architecture. See dependency inversion for the pattern behind it.

Package cohesion and coupling

Which classes belong together? Two classic principles help:

  • Common Closure: classes that change for the same reason belong in the same package.
  • Common Reuse: classes that are used together belong together; do not force users to depend on things they do not use.

You can measure the result. Robert Martin's metrics for a package P are:

  • Afferent coupling (Ca): number of packages that depend on P (incoming arrows).
  • Efferent coupling (Ce): number of packages P depends on (outgoing arrows).
  • Instability I = Ce / (Ca + Ce): 0 means maximally stable (everyone depends on it, it depends on nothing), 1 means unstable.

Healthy dependencies point toward more stable packages. If a stable package (I near 0) depends on an unstable one (I near 1), a change in the unstable one ripples to many.

Nesting and naming

Packages can nest to any depth, but two or three levels are enough for readability. Prefer names from the problem domain (billing, shipping) over technical names (managers, helpers) because domain packages stay stable when technology changes. Beware of packages by kind (all controllers in one place) in large systems: features then scatter across many packages. Organizing by feature (vertical slices) keeps changes local.

Metrics for a package model

The first example computes afferent and efferent coupling and instability from a dependency list.

Python Coupling and instability per package

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

util has I = 0: everyone depends on it and it depends on nothing, so it must be very stable. ui has I = 1.0: nobody depends on it, so it can change freely. That is the desired shape.

Checking layer rules

A script can enforce layering rules in a build, so that the diagram is not just a picture.

Python Detect forbidden dependencies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In real projects tools check such rules for you (ArchUnit in Java, import-linter in Python, dependency-cruiser in JavaScript). The diagram is the specification; the tool is the guard.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between import and access between packages?

    Both need public elements, but import merges the names into the namespace.
  2. 2. A package has Ca = 4 and Ce = 0. What is its instability?

    I = Ce / (Ca + Ce) = 0 / 4 = 0: fully stable.
  3. 3. Which arrangement is a layering violation?

    A lower layer such as domain must not know about the presentation layer.
  4. 4. Why prefer feature-based packages in large systems?

    Grouping by feature follows the Common Closure idea: things that change together live together.

Summary

  • A package is a namespace; a package diagram shows groups of elements and their dependencies.
  • Dependency, import, access and merge are the relationships; only public elements are visible.
  • Use packages to express layers: one-way arrows, no cycles, stable core.
  • Ca, Ce and instability quantify coupling; dependencies should point toward stability.
  • Enforce the diagram with tools so that the code keeps matching it.

Next: Profiles and Stereotypes