Mastering Logistics Workflows: A Freight Forwarding Use Case Diagram Tutorial with PlantUML

@startuml
!include https://static.visual-paradigm.com/web/resources/plantuml-stdlib/themes/rose.puml

title Freight Forwarding System Use Case Diagram

/'
  This use case diagram models the core functionalities of a Freight Forwarding System.
  The system serves as a platform that connects shippers (clients needing to transport goods)
  with carriers (transportation providers). Primary actors are users who directly initiate
  interactions with the system to manage shipments, track cargo, and handle documentation.
  Secondary actors represent external entities that the system interacts with to fulfill
  its core services, such as customs authorities for clearance and carrier systems for
  booking and tracking updates.
'/

left to right direction

rectangle "Freight Forwarding System" {
  usecase "Request Quote" as UC1
  usecase "Book Shipment" as UC2
  usecase "Track Shipment" as UC3
  usecase "Manage Shipment Documents" as UC4
  usecase "Process Customs Clearance" as UC5
  usecase "Generate Invoice" as UC6
  usecase "Receive Payment" as UC7
  usecase "Schedule Pickup" as UC8
  usecase "Notify Status Change" as UC9
  usecase "Request Route Optimization" as UC10
}

' Primary actors
actor "Shipper" as Shipper
actor "Customer Service Rep" as CSR

' Secondary actors
actor "Carrier System" as Carrier
actor "Customs Authority" as Customs

' Primary actor associations
Shipper -- UC1
Shipper -- UC2
Shipper -- UC3
Shipper -- UC4
Shipper -- UC6
Shipper -- UC8

CSR -- UC4
CSR -- UC5
CSR -- UC6
CSR -- UC7
CSR -- UC8

' Secondary actor associations
UC3 --- Carrier
UC5 --- Customs
UC9 -- Shipper
UC9 -- CSR
UC9 --- Carrier

' Extended use case
UC10 <.. UC2 : <<extend>>
Shipper -- UC10

@enduml

Step-by-Step Architectural Walkthrough

Now, let’s deconstruct the code to understand how each piece contributes to the final visualization. We will build this in four logical phases.

Phase 1: Canvas Configuration & Layout Directives

Every PlantUML diagram starts with setup. We begin by including a theme to ensure professional styling and setting the layout direction. In logistics, processes often flow chronologically from left to right.

First, we include the rose theme to apply a consistent color palette and border style:

!include https://static.visual-paradigm.com/web/resources/plantuml-stdlib/themes/rose.puml

Next, we define the global layout direction to align the actors and use cases horizontally:

left to right direction

Phase 2: Declaring Core Entities, Actors, and Boundaries

The core of a Use Case Diagram is the system boundary. We define this using a rectangle element. Inside this boundary, we declare the use cases.

We assign IDs (like UC1, UC2) to each use case. This allows us to reference them later when drawing connections, keeping the code clean and readable.

rectangle "Freight Forwarding System" {
  usecase "Request Quote" as UC1
  usecase "Book Shipment" as UC2
  usecase "Track Shipment" as UC3
  ... 
}

Outside the rectangle, we declare the actors. Notice how we assign aliases (e.g., as Shipper) to make the connection syntax cleaner.

actor "Shipper" as Shipper
actor "Customer Service Rep" as CSR
actor "Carrier System" as Carrier
actor "Customs Authority" as Customs

Phase 3: Mapping Data Flows & Key Interactions

Here we define the relationships between actors and use cases. In PlantUML, a standard association is drawn with --. This creates a line without arrowheads, which is standard for Use Case diagrams to indicate participation.

We map the primary actors (Shipper, CSR) to their respective functions:

Shipper -- UC1
Shipper -- UC2
CSR -- UC4

Secondary actors, such as the Carrier System, interact differently. For example, the Track Shipment use case relies on data from the Carrier System. We use a dashed line --- to indicate this dependency.

UC3 --- Carrier
UC5 --- Customs

Phase 4: Grouping, Annotations & Visual Polish

Finally, we handle optional or extended behaviors. The diagram includes an Extend relationship. This indicates that Request Route Optimization (UC10) is an optional extension of the Book Shipment (UC2) process. In PlantUML, this is denoted by <..> with a stereotype label.

UC10 <.. UC2 : <>

We also add a title and a comment block to document the context of the diagram, ensuring that anyone viewing the code understands the business scenario immediately.

title Freight Forwarding System Use Case Diagram
/'
  This use case diagram models the core functionalities...
'/

Syntax & Keyword Deep Dive

Understanding the specific keywords used in this diagram is essential for mastering PlantUML. Here is a breakdown of the critical syntax elements:

• @startuml / @enduml: These are the mandatory delimiters that tell the parser where the diagram definition begins and ends.
• !include: This directive imports external resources, such as the rose.puml theme file, to style the diagram without writing custom CSS.
• rectangle: Defines the system boundary. Anything inside this box is considered part of the system; anything outside is an external actor.
• usecase: Defines a specific functional goal or service provided by the system. The as keyword assigns a short alias for easier referencing.
• actor: Defines an external entity (human or system) that interacts with the system.
• -- (Association): Connects an actor to a use case. It indicates that the actor participates in the use case.
• --- (Dependency): Used for secondary actors. It indicates that the use case depends on information from the external system.
• <..> (Extension): Indicates that one use case (UC10) extends another (UC2) under specific conditions.

Best Practices & Pitfalls to Avoid

To maintain high-quality documentation, follow these modeling best practices:

1. Keep Use Cases Atomic: Ensure each use case represents a single, distinct goal. For example, “Manage Shipment Documents” is better than “Manage Everything”.
2. Separate Primary and Secondary Actors: Clearly distinguish between users who drive the process (Shipper) and systems that support it (Carrier). This helps developers identify API integration requirements.
3. Use Meaningful Names: Avoid generic names like “Do Stuff”. Use verb-noun phrases like “Request Quote” or “Process Customs Clearance” to make the diagram self-documenting.
4. Limit Scope: Do not try to model every single button click in the UI. Focus on the high-level business capabilities that deliver value to the actor.

Try It Yourself with VPasCode