Packages: Organizational Tool for Managing Complexity

Purpose of Packages

Function: What Package Diagrams Model

// Package Diagram: Layered Architecture

┌─────────────────────────────────────┐
│      Presentation Layer             │
│  - Controllers                      │
│  - View Models                      │
│  - API Endpoints                    │
└────────────┬────────────────────────┘
             │ depends on
             ▼
┌─────────────────────────────────────┐
│      Business Layer                 │
│  - Domain Entities                  │
│  - Business Rules                   │
│  - Use Case Handlers                │
└────────────┬────────────────────────┘
             │ depends on
             ▼
┌─────────────────────────────────────┐
│      Data Access Layer              │
│  - Repositories                     │
│  - Database Entities                │
│  - Query Builders                   │
└─────────────────────────────────────┘

// Package dependencies enforce:
// - Unidirectional dependency flow (top → bottom)
// - Presentation cannot access Data Access directly
// - Business layer has no UI dependencies
// - Circular dependencies prohibited

Packages vs Components vs Modules

Package Mapping to Physical Structures

Domain-Driven Design and Bounded Contexts

// Package Organization: Domain-Driven Design Bounded Contexts

com.ecommerce
├── catalog                    // Bounded Context: Product Catalog
│   ├── domain
│   │   ├── Product.java
│   │   ├── Category.java
│   │   └── ProductRepository.java
│   └── api
│       └── CatalogService.java
│
├── cart                       // Bounded Context: Shopping Cart
│   ├── domain
│   │   ├── Cart.java
│   │   ├── CartItem.java
│   │   └── CartRepository.java
│   └── api
│       └── CartService.java
│
├── order                      // Bounded Context: Order Processing
│   ├── domain
│   │   ├── Order.java
│   │   ├── OrderItem.java
│   │   └── OrderRepository.java
│   └── api
│       └── OrderService.java
│
└── payment                    // Bounded Context: Payment Processing
    ├── domain
    │   ├── Payment.java
    │   ├── PaymentMethod.java
    │   └── PaymentGateway.java
    └── api
        └── PaymentService.java

// Package dependencies show context relationships:
// - cart → catalog (needs product information)
// - order → catalog (order contains products)
// - order → payment (order triggers payment)
// - No circular dependencies between contexts

Modern Language Module Systems

// Java Module: Formal Package Encapsulation

// module-info.java (Module Declaration)
module com.ecommerce.order {
    requires com.ecommerce.catalog;  // Dependency declaration
    requires com.ecommerce.payment;
    
    exports com.ecommerce.order.api; // Public package
    
    // com.ecommerce.order.domain is package-private
    // External modules cannot access domain package
}

// JPMS advantages:
// - Compiler enforces dependency declarations
// - Private packages truly inaccessible (no reflection hacks)
// - Circular dependencies detected at compile time
// - Reliable encapsulation enables modular evolution

What Modern Practice Replaced

// Architecture Fitness Function: Enforcing Package Rules

// ArchUnit (Java): Package Dependency Rules as Tests
@Test
public void layeredArchitecture_shouldBeRespected() {
    layeredArchitecture()
        .layer("Presentation").definedBy("..presentation..")
        .layer("Business").definedBy("..business..")
        .layer("DataAccess").definedBy("..dataaccess..")
        
        .whereLayer("Presentation").mayNotBeAccessedByAnyLayer()
        .whereLayer("Business").mayOnlyBeAccessedByLayers("Presentation")
        .whereLayer("DataAccess").mayOnlyBeAccessedByLayers("Business")
        
        .check(classes);
}

@Test
public void noCyclesInPackageDependencies() {
    slices()
        .matching("com.ecommerce.(*)..")
        .should().beFreeOfCycles()
        .check(classes);
}

// Tests fail if:
// - Presentation accesses DataAccess directly
// - Circular dependencies exist between packages
// - Layering violations introduced

Where Package Diagrams Remain Valuable

Modern Tooling

// PlantUML: Package Diagram as Code

@startuml
package "Presentation Layer" {
  [Controllers]
  [ViewModels]
}

package "Business Layer" {
  [Domain Entities]
  [Use Cases]
  [Business Rules]
}

package "Data Access Layer" {
  [Repositories]
  [Database Entities]
}

[Controllers] --> [Use Cases]
[Use Cases] --> [Domain Entities]
[Domain Entities] --> [Repositories]
[Repositories] --> [Database Entities]

@enduml

// Benefits:
// - Text format (version control friendly)
// - Generate images automatically
// - UML-compliant package notation

Conclusion