UML Package Diagrams

Complete guide to UML Package Diagrams: learn how to organize system elements into packages, manage dependencies, and structure large systems. Master package organization and namespace management.

1. What are Package Diagrams?
2. Packages
3. Package Relationships
4. Package Stereotypes
5. Organizing Packages
6. Best Practices
7. Practical Examples
8. Conclusion

1. What are Package Diagrams?

Package diagrams show how model elements are organized into packages and the dependencies between packages. They help manage complexity in large systems by grouping related elements together.

Package diagrams are used to:

Organize large models into manageable units
Show system structure and organization
Manage namespaces and avoid naming conflicts
Document package dependencies
Plan system architecture and modularity

Packages are similar to namespaces or modules in programming languages—they group related elements and provide a way to organize and manage complexity.

2. Packages

2.1 What is a Package?

A package is a container for organizing model elements such as classes, components, and other packages. Packages help:

Group related elements together
Provide namespaces to avoid naming conflicts
Control visibility and access
Organize large models

2.2 Package Notation

Packages are shown as rectangles with a tab (folder icon):

@startuml package Package { class Element1 class Element2 } note right of Package Packages shown with tab (folder icon) end note @enduml

2.3 Package Name

Package names should:

Be unique within their namespace

Use reverse domain notation (com.company.module)

Be descriptive and meaningful

Follow consistent naming conventions

2.4 Nested Packages

Packages can contain other packages, creating a hierarchy:

@startuml package "com.company" { package order { class Order } package payment { class Payment } } @enduml

3. Package Relationships

3.1 Dependency

A dependency shows that one package depends on another. Shown as a dashed arrow.

@startuml package OrderPackage { class Order } package PaymentPackage { class Payment } OrderPackage ..> PaymentPackage @enduml

This means elements in OrderPackage use elements from PaymentPackage.

3.2 Import

An import is a type of dependency that allows public elements of one package to be referenced using unqualified names. Shown with <> stereotype.

@startuml package OrderPackage { class Order } package CommonPackage { class Common } OrderPackage ..> CommonPackage : <> @enduml

3.3 Access

An access relationship is similar to import but uses qualified names. Shown with <> stereotype.

@startuml package OrderPackage { class Order } package CommonPackage { class Common } OrderPackage ..> CommonPackage : <> @enduml

3.4 Merge

A merge relationship combines the contents of two packages. Shown with <> stereotype.

@startuml package OrderPackage { class Order } package ExtendedOrderPackage { class ExtendedOrder } OrderPackage ..> ExtendedOrderPackage : <> @enduml

3.5 Generalization

Packages can have generalization relationships, where one package specializes another:

@startuml package BasePackage { class Base } package DerivedPackage { class Derived } DerivedPackage --|> BasePackage @enduml

4. Package Stereotypes

4.1 Common Stereotypes

Packages can be stereotyped to indicate their purpose:

<>: Represents a complete model
<>: Represents a subsystem
<>: Represents a framework
<>: Represents a library
<>: Represents an architectural layer

4.2 Stereotype Notation

@startuml package "<>\nPresentation" as Presentation { class Controller } @enduml

4.3 Using Stereotypes

Stereotypes help:

Clarify package purpose
Organize packages by type
Document architectural layers
Distinguish frameworks from application code

5. Organizing Packages

5.1 By Functionality

Organize packages by business functionality:

com.company
  ├── order
  ├── payment
  ├── inventory
  └── shipping

5.2 By Layer

Organize packages by architectural layers:

com.company
  ├── presentation
  ├── business
  ├── data
  └── common

5.3 By Component

Organize packages by system components:

com.company
  ├── order-service
  ├── payment-service
  └── inventory-service

5.4 Hybrid Organization

Combine approaches for large systems:

com.company
  ├── order
  │   ├── presentation
  │   ├── business
  │   └── data
  └── payment
      ├── presentation
      ├── business
      └── data

6. Best Practices

6.1 Cohesive Packages

Group related elements together
Keep packages focused on a single responsibility
Avoid packages with unrelated elements
Use clear, descriptive package names

6.2 Manage Dependencies

Minimize dependencies between packages
Avoid circular dependencies
Depend on stable packages
Use interfaces to reduce coupling

6.3 Consistent Organization

Follow consistent naming conventions
Use the same organization pattern throughout
Keep package hierarchies shallow (3-4 levels)
Document package organization decisions

6.4 Visibility

Control what's visible outside packages
Hide implementation details
Expose only public interfaces
Use package visibility appropriately

6.5 Size Management

Keep packages at manageable sizes
Split large packages into smaller ones
Don't create too many small packages
Balance granularity with manageability

7. Practical Examples

7.1 Layered Architecture

@startuml package Presentation { class Controller } package Business { class Service } package Data { class Repository } Presentation ..> Business : depends on Business ..> Data : depends on @enduml

7.2 Domain-Driven Design

@startuml package "com.company" { package order { package domain package application package infrastructure } package payment { package domain package application package infrastructure } package shared { package kernel } } @enduml

7.3 Microservices Organization

@startuml package "com.company" { package "order-service" { package order } package "payment-service" { package payment } package common { package api package utils } } @enduml