Package diagram

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

Package diagrams show grouping and dependency at the module level. They are most valuable when you suspect a dependency cycle, because a cycle is immediately visible.

Small, cheap, and worth drawing before a refactor.

#When to draw one

  • Planning a refactor or a module split.

  • Documenting a codebase's structure for new joiners.

  • Finding dependency cycles.

#What is on the diagram

Element

Meaning

Package

A folder-shaped box

Dependency

A dashed arrow: this package uses that one

Nesting

Packages drawn inside packages

Import and access

Stereotypes on a dependency, when the distinction matters

#A worked example

Packages with a dependency cycle worth arguing about:

Package diagram

The source, which you can paste into a new diagram and edit:

@startuml
package "web" {
}
package "api" {
}
package "domain" {
  package "orders" {}
  package "billing" {}
}
package "infrastructure" {
  package "persistence" {}
  package "messaging" {}
}
package "shared" {
}

web ..> api
api ..> domain
domain.orders ..> shared
domain.billing ..> shared
domain.orders ..> domain.billing
domain.billing ..> domain.orders
api ..> infrastructure.persistence
infrastructure.messaging ..> domain.orders
@enduml

#A few things that catch people out

  • Arrows point from the dependent package to the one it depends on. Reversing them inverts the meaning.

  • Cycles are the reason to draw this. Do not tidy them away; that is the finding.

  • Keep it to one level of nesting or it becomes unreadable.

Four types cover most of it.