Code Organization & Structure

Project structure tells us where files live. Package organization tells us how those files relate to each other—what depends on what, what should be public versus private, and how the codebase decomposes into coherent, reusable units.

A package (also called a module, library, or component depending on your language ecosystem) is a unit of organization larger than a class but smaller than an entire application. It groups related classes that collaborate to provide a cohesive capability, while hiding implementation details from the rest of the system.

Mastering package organization is critical for LLD because it determines the stability of your design. Well-packaged code is easy to understand, test, and modify in isolation. Poorly packaged code creates ripple effects where every change touches seemingly unrelated parts of the system.

Before diving into organization principles, let's establish what we mean by 'package' across different ecosystems. The concept is universal, but terminology varies:

Characteristics of a well-designed package:

Regardless of language, good packages share common traits:

1. Single, clear purpose — You can describe what the package does in one sentence without using 'and'.

2. Cohesive contents — The classes within the package work together; removing any class would break the package's functionality.

3. Minimal public surface — Only necessary classes, interfaces, and functions are exposed; implementation details are hidden.

4. Explicit dependencies — What the package needs from outside is clearly stated (through imports, dependencies, or injection).

5. Independent testability — The package can be tested in isolation, with external dependencies mocked or stubbed.

6. Versioned evolution — The package can evolve without breaking consumers, following semantic versioning principles.

Cohesion refers to how strongly related the elements within a package are. High cohesion means the package has a focused purpose; low cohesion means it's a grab-bag of unrelated elements. Robert C. Martin (Uncle Bob) formalized three principles that guide package cohesion:

The tension between principles:

These principles create tension that must be balanced:

• REP + CCP push toward larger packages — more classes mean more reuse potential and fewer deployments for changes.
• CRP pushes toward smaller packages — fewer unnecessary dependencies mean lighter consumer burden.

The cohesion tension triangle:

        REP
        ╱╲
       ╱  ╲
      ╱    ╲
     ╱      ╲
   CCP──────CRP

• Favor REP+CCP: Packages are harder to use (too much baggage)
• Favor REP+CRP: Packages change too often (many small releases)
• Favor CCP+CRP: Packages are hard to reuse (too narrowly focused)

The art of package design is finding the balance appropriate for your context—prioritizing reuse for libraries, change management for rapidly evolving features, or minimal dependencies for stable infrastructure.

Coupling refers to the degree of interdependence between packages. High coupling means packages are tightly interconnected; a change in one requires changes in many others. Low coupling means packages are independent; they can evolve separately. Three principles guide coupling management:

Visualizing package dependencies:

Package dependencies should form a Directed Acyclic Graph (DAG)—arrows only point one way, and following arrows never brings you back to where you started:

✅ Acyclic (Valid)
                     ┌─────────────┐
                     │    Core     │
                     └──────┬──────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │  Orders  │  │ Products │  │  Users   │
       └────┬─────┘  └──────────┘  └────┬─────┘
            │                           │
            └──────────┬────────────────┘
                       ▼
               ┌──────────────┐
               │  Web/API     │
               └──────────────┘

❌ Cyclic (Invalid)
       ┌──────────┐              ┌──────────┐
       │  Orders  │─────────────▶│ Products │
       └────▲─────┘              └────┬─────┘
            │                         │
            └─────────────────────────┘

Stability metrics:

Stability can be measured by counting dependencies:

Instability (I) = Ce / (Ca + Ce)

Where:
• Ca = Afferent couplings (incoming dependencies—packages that depend on this one)
• Ce = Efferent couplings (outgoing dependencies—packages this one depends on)
• I ranges from 0 (maximally stable) to 1 (maximally unstable)

Example:

• A core Domain package has 10 packages depending on it (Ca=10) and depends on nothing except standard library (Ce=0): I = 0/(10+0) = 0 (very stable)
• A WebAPI package has nothing depending on it (Ca=0) and depends on 5 packages (Ce=5): I = 5/(0+5) = 1 (very unstable)

SDP requires dependencies to flow toward lower I values. The WebAPI (I=1) depending on Domain (I=0) is correct. Domain depending on WebAPI would violate SDP.

A package's public API is the contract it exposes to consumers. Everything else is implementation detail that can change freely. Thoughtful API design is essential for maintainable package organization.

The barrel pattern:

Many languages support 'barrel' or 'index' files that export the public API of a package:

Managing dependencies between packages is one of the most challenging aspects of large-scale software organization. Poor dependency management leads to the dreaded 'ball of mud' architecture where everything depends on everything.

Dependency direction strategies:

Dependency injection at package boundaries:

When Package A needs functionality from Package B, there are several approaches:

Direct dependency (tight coupling):

// orders/OrderService.ts
import { EmailService } from '../notifications/EmailService';

class OrderService {
    private emailService = new EmailService();
    // Orders package now depends on Notifications package
}

Interface-based dependency (loose coupling):

// orders/ports/NotificationPort.ts (in Orders package)
interface NotificationPort {
    sendOrderConfirmation(orderId: string): Promise<void>;
}

// orders/OrderService.ts
class OrderService {
    constructor(private notifications: NotificationPort) {}
    // Orders defines what it needs; doesn't know about email specifics
}

// notifications/EmailNotificationAdapter.ts (in Notifications package)
import { NotificationPort } from '../orders/ports/NotificationPort';

class EmailNotificationAdapter implements NotificationPort {
    async sendOrderConfirmation(orderId: string): Promise<void> {
        // Email implementation
    }
}

With interface-based dependencies, the Orders package remains stable—it defines its needs but doesn't depend on implementations. The Notifications package depends on the Orders interface, inverting the typical dependency direction.

Monorepos contain multiple packages in a single repository, enabling shared tooling, atomic changes across packages, and simplified dependency management. They've become popular at scale (Google, Meta, Microsoft all use monorepos).

Typical monorepo structure:

├── package.json              # Root workspace configuration
├── packages/                 # Application packages
│   ├── web/                  # Web frontend
│   │   ├── package.json
│   │   └── src/
│   ├── api/                  # Backend API
│   │   ├── package.json
│   │   └── src/
│   └── mobile/               # Mobile app
│       ├── package.json
│       └── src/
├── libs/                     # Shared library packages
│   ├── core/                 # Domain models, shared types
│   │   ├── package.json
│   │   └── src/
│   ├── ui-components/        # Shared UI components
│   │   ├── package.json
│   │   └── src/
│   └── utils/                # Shared utilities
│       ├── package.json
│       └── src/
├── tools/                    # Build and development tools
│   ├── eslint-config/
│   └── typescript-config/
└── docs/                     # Shared documentation

Recognizing common anti-patterns helps you avoid them. Here are the most damaging mistakes in package organization:

Designing package structure shouldn't be ad-hoc. Here's a systematic process for organizing code into packages:

Example: E-commerce package decomposition

Starting from a monolithic structure, let's design packages:

Step 1: Domain boundaries

• Catalog (products, categories)
• Shopping (cart, wishlist)
• Checkout (orders, payments)
• Fulfillment (shipping, inventory)
• Identity (users, authentication)

Step 2: Common dependencies

• Domain primitives (Money, Address, Quantity)
• Event infrastructure (event bus, serialization)
• Common utilities (validation, formatting)

Step 3: Resulting structure

@shop/domain-primitives  ← Very stable, no dependencies
@shop/catalog            ← Depends on domain-primitives
@shop/shopping           ← Depends on domain-primitives, catalog
@shop/checkout           ← Depends on domain-primitives, shopping
@shop/fulfillment        ← Depends on domain-primitives, checkout
@shop/identity           ← Depends on domain-primitives
@shop/api-gateway        ← Depends on all feature packages

Modern tooling can enforce package boundaries and dependency constraints, catching architectural violations before they reach production:

We've explored package organization in depth. Let's consolidate the essential insights:

What's next:

With project structure and package organization covered, we now turn to naming conventions—the art of choosing names that communicate intent, maintain consistency, and make code self-documenting at every level from variables to packages.