Package Diagram in UML

Introduction

As software systems grow, managing complexity becomes more about organization than just writing code. In Java, we use packages to group related classes. Similarly, in UML, we use Package Diagrams to visually organize large systems into logical containers and show how these containers relate to one another.

This tutorial will help you understand how to use UML Package Diagrams to group classes, manage dependencies, and improve codebase structure. We'll walk through Java-based examples using a school management system scenario to make concepts easy and relatable.

What is a Package Diagram?

A Package Diagram in UML is a structural diagram that groups related classes into packages and shows the dependencies between those packages. It gives you a high-level view of the system architecture — helping you visualize the logical partitioning of the system.

Why Use Package Diagrams?

• Organize large systems: Divide the system into manageable parts
• Visualize module interaction: Show which packages rely on others
• Improve maintainability: Reduce tight coupling and circular dependencies
• Align code structure: Match your UML packages with Java package structure

Basic Elements of a Package Diagram

1. Package

Represented as a folder icon. Each package may contain other packages, classes, interfaces, or diagrams.

package student

2. Class Inside a Package

Classes or interfaces can be placed inside the package visually. Alternatively, we just show dependencies at the package level.

3. Dependency

A dashed arrow from one package to another shows that one package depends on the other — meaning it uses its classes or interfaces.

student --> database

Example: School Management System

Let’s say we have a Java-based school management system. We might logically group it into the following packages:

• com.school.student
• com.school.teacher
• com.school.result
• com.school.database

Java Package Structure

// com.school.student.Student.java
public class Student {
  private String name;
  private int rollNumber;
}

// com.school.teacher.Teacher.java
public class Teacher {
  private String name;
  private String subject;
}

// com.school.result.ResultService.java
public class ResultService {
  public void generateResult(Student student) {
    // logic
  }
}

// com.school.database.DBConnection.java
public class DBConnection {
  public static Connection connect() { ... }
}

UML Package Diagram

Here’s how we could represent the above in a package diagram:

package com.school.student
package com.school.teacher
package com.school.result
package com.school.database

com.school.result --> com.school.student
com.school.result --> com.school.database
com.school.teacher --> com.school.database

How to Create a Package Diagram: Step-by-Step

Step 1: Identify Packages

Group classes based on functionality, responsibility, or layer (e.g., controller, service, DAO).

Step 2: Define Package Relationships

Draw dependencies based on actual usage. For example, if ResultService uses Student, draw a dependency from result to student.

Step 3: Keep the Diagram High-Level

Package diagrams should focus on inter-package relationships, not internal class details. You can always complement it with a class diagram later.

Step 4: Use UML Notation

• Package: Folder-like rectangle with name
• Dependency: Dashed arrow from dependent to provider package

Advanced Concepts

Nested Packages

Packages can be nested to show deeper hierarchies.

Import Relationships

Use notes or stereotypes to indicate import or access restrictions, such as "public API" or "internal only."

Package Merge

Merge is a special kind of dependency that unifies two packages into one logical package. Rarely used but useful in frameworks.

Best Practices

• Keep packages cohesive: Group only closely related classes
• Minimize dependencies: Avoid circular dependencies and tight coupling
• Follow naming conventions: Use consistent, readable names (e.g., com.school.result)
• Align with code: Make sure your UML packages reflect your actual Java package structure

Use Cases of Package Diagrams

• Planning: Before writing code, structure your packages visually
• Refactoring: Identify and break circular dependencies or tightly coupled packages
• Documentation: Show high-level architecture to new developers or stakeholders
• Testing: Understand module-level boundaries for unit and integration testing

Tools to Create Package Diagrams

• StarUML: Drag-and-drop UML package support with clean visuals
• PlantUML: Great for text-based diagram generation
• Lucidchart: Collaborative, intuitive UI for modular designs
• draw.io: Free tool with templates for UML packages

PlantUML Example

@startuml
package "com.school.student" {
}

package "com.school.teacher" {
}

package "com.school.result" {
}

package "com.school.database" {
}

com.school.result --> com.school.student
com.school.result --> com.school.database
com.school.teacher --> com.school.database
@enduml

Conclusion

Package diagrams are your blueprint for organizing and understanding system structure at scale. They bring order to complexity, prevent architectural drift, and provide clarity during design, refactoring, and onboarding.

Especially in Java development, where code is naturally organized into packages, UML Package Diagrams make it easy to visualize and communicate your system’s logical architecture.

Next, we’ll transition into behavioral modeling with Use Case Diagrams — perfect for defining what users can do within your system.