# Package diagram

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](https://help.gocapable.com/images/att1418559493.svg)

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.

---

## Related

[UML timing diagramState against a time axis.](https://help.gocapable.com/diagrams/uml-timing-diagram.html)

[Class diagramTypes, fields and the relationships between them.](https://help.gocapable.com/diagrams/class-diagram.html)

[UML diagramsBack to the UML overview.](https://help.gocapable.com/diagrams/uml-diagrams.html)

---

_Four types cover most of it._