Package Diagrams & Architecture

Package Diagrams

A Package Diagram shows how a system is organized into packages (namespaces/modules) and the dependencies between them. It's a high-level architectural view that helps you understand the big picture before diving into class-level details.

Package Diagram Notation:

  Package:
  ┌────────────────────────┐
  │ «package»              │
  │ PackageName            │
  ├────────────────────────┤
  │                        │
  │  Classes inside        │
  │                        │
  └────────────────────────┘

  Dependency (dashed arrow):
  PackageA - - - - -▶ PackageB
  "PackageA depends on PackageB"

  Import (solid arrow with «import»):
  PackageA ────▶ PackageB «import»
  "PackageA imports PackageB's public elements"

Example: E-Commerce Architecture

┌──────────────────────────────────────────────────────────────┐
│                    «presentation»                            │
│                    Presentation Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ WebUI        │  │ MobileUI     │  │ AdminUI      │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼───────────────┘
          │ - - - - - - - - │ - - - - - - - - │
          ▼                 ▼                 ▼
┌──────────────────────────────────────────────────────────────┐
│                    «application»                             │
│                    Application Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ OrderService │  │ UserService  │  │ PaymentService│      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼───────────────┘
          │ - - - - - - - - │ - - - - - - - - │
          ▼                 ▼                 ▼
┌──────────────────────────────────────────────────────────────┐
│                    «domain»                                  │
│                    Domain Layer                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │  Order   │ │ Customer │ │ Product  │ │ Payment  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
└──────────────────────────────────────────────────────────────┘
          │ - - - - - - - - │ - - - - - - - - │
          ▼                 ▼                 ▼
┌──────────────────────────────────────────────────────────────┐
│                    «infrastructure»                          │
│                    Infrastructure Layer                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ DatabaseRepo │  │ EmailService │  │ PaymentGateway│      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└──────────────────────────────────────────────────────────────┘

Dependency Rule:
  Dependencies point INWARD (toward the domain).
  Outer layers depend on inner layers, never the reverse.
  Domain layer has ZERO dependencies on infrastructure.

Layered Architecture

The most common architectural pattern — organizing code into horizontal layers with clear dependency rules:

┌─────────────────────────────────────────┐
│  Presentation Layer                     │
│  • UI components, controllers           │
│  • Handles user input and display       │
├─────────────────────────────────────────┤
│  Application Layer                      │
│  • Use cases, application services      │
│  • Coordinates domain objects           │
├─────────────────────────────────────────┤
│  Domain Layer                           │
│  • Business entities and rules          │
│  • Core logic, no framework dependencies│
├─────────────────────────────────────────┤
│  Infrastructure Layer                   │
│  • Database access, external APIs       │
│  • File system, network communication   │
└─────────────────────────────────────────┘

Benefits:
  ✓ Clear separation of concerns
  ✓ Each layer can be tested independently
  ✓ Infrastructure can be swapped without changing domain

Drawbacks:
  ✗ Can become rigid (change in one layer affects others)
  ✗ Performance overhead from layering

Package Design Principles

1. Stable Dependencies Principle
   ──────────────────────────────
   Depend in the direction of stability.
   Stable packages should not depend on unstable ones.

2. Stable Abstractions Principle
   ──────────────────────────────
   The more stable a package, the more abstract it should be.

3. Common Reuse Principle
   ───────────────────────
   Classes that are reused together should be packaged together.

4. Common Closure Principle
   ────────────────────────
   Classes that change for the same reason should be in the same package.

Package Organization Strategies:

  By Feature (recommended for most projects):
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ Orders   │ │ Products │ │ Users    │
    │          │ │          │ │          │
    │ • Model  │ │ • Model  │ │ • Model  │
    │ • Service│ │ • Service│ │ • Service│
    │ • Repo   │ │ • Repo   │ │ • Repo   │
    │ • API    │ │ • API    │ │ • API    │
    └──────────┘ └──────────┘ └──────────┘

  By Layer (traditional):
    ┌──────────────────────────────┐
    │ Controllers                  │
    ├──────────────────────────────┤
    │ Services                     │
    ├──────────────────────────────┤
    │ Models                       │
    ├──────────────────────────────┤
    │ Repositories                 │
    └──────────────────────────────┘