Code Organization & Structure

When we discuss Low-Level Design, we often focus on classes, interfaces, patterns, and principles. We draw UML diagrams, reason about dependencies, and craft elegant abstractions. But there's a dimension of design that's equally critical yet frequently overlooked: how do we organize all of this code in actual files and directories?

Project structure is not merely an administrative concern—it's a fundamental design decision that shapes developer experience, onboarding velocity, refactoring safety, and system evolution. A well-structured project communicates intent. It tells developers where to find things, where to add new features, and how different parts of the system relate. A poorly structured project, regardless of how elegant its internal classes are, becomes a maze that slows development and accumulates technical debt.

This page explores project structure as a first-class design concern—one that deserves the same rigor and intentionality we apply to class design and pattern selection.

Many developers treat project structure as a minor concern—something to set up once and forget. This perspective dramatically underestimates the impact of structure on software quality. Consider that developers spend more time reading code than writing it, and much of that reading involves finding the right code to read.

Project structure is the information architecture of your codebase. Just as a well-designed library has a logical catalog system that helps patrons find books, a well-structured project has a logical organization that helps developers find code. The alternative—a flat sea of files or an arbitrary nest of folders—forces developers to rely on global search, institutional knowledge, or trial and error.

The cognitive load dimension:

Every codebase has a mental model—how developers think about its organization. When the physical structure (files and directories) matches the mental model (how we think about the domain), cognitive load is minimized. When they diverge, developers must maintain a translation layer in their heads, consuming mental resources that could be applied to actual problem-solving.

Consider two approaches to organizing an e-commerce system:

Structure A (Mental Model Mismatch):

src/
  controllers/
    OrderController.ts
    ProductController.ts
    UserController.ts
  services/
    OrderService.ts
    ProductService.ts
    UserService.ts
  repositories/
    OrderRepository.ts
    ProductRepository.ts
    UserRepository.ts

Structure B (Mental Model Alignment):

src/
  orders/
    OrderController.ts
    OrderService.ts
    OrderRepository.ts
    Order.ts
  products/
    ProductController.ts
    ProductService.ts
    ProductRepository.ts
    Product.ts
  users/
    UserController.ts
    UserService.ts
    UserRepository.ts
    User.ts

In Structure A, working on 'orders' requires navigating three different directories. In Structure B, everything related to orders lives together. Neither is universally correct—context matters—but this illustrates how structure affects the mental effort required to work with code.

Before examining specific structural patterns, we need to establish the principles that guide good project organization. These principles are language-agnostic and apply whether you're building in Java, TypeScript, Python, C#, or any other object-oriented language.

The cost of reorganization:

Changing project structure after a codebase has grown is expensive. Unlike refactoring code—where IDE tools can safely rename and move—restructuring directories affects:

• All import statements across the codebase
• Build system configurations
• Test configurations and fixtures
• Documentation and onboarding materials
• IDE configurations and bookmarks
• Version control history (git move vs. delete/add)
• Deployment scripts and CI/CD pipelines

This high cost of change means that initial structure decisions carry long-term consequences. It's worth investing time upfront to establish a structure that will scale, rather than planning to 'fix it later' when the codebase is larger.

The layered structure organizes code by technical layer—controllers together, services together, repositories together. This is the most common pattern in enterprise applications and the default structure generated by most frameworks and scaffolding tools.

Characteristic structure:

src/
├── controllers/           # HTTP/API endpoints
│   ├── OrderController.ts
│   ├── ProductController.ts
│   └── UserController.ts
├── services/              # Business logic layer
│   ├── OrderService.ts
│   ├── ProductService.ts
│   └── UserService.ts
├── repositories/          # Data access layer
│   ├── OrderRepository.ts
│   ├── ProductRepository.ts
│   └── UserRepository.ts
├── models/                # Domain entities
│   ├── Order.ts
│   ├── Product.ts
│   └── User.ts
├── dtos/                  # Data transfer objects
│   ├── CreateOrderDto.ts
│   ├── ProductResponseDto.ts
│   └── UserRegistrationDto.ts
└── utils/                 # Shared utilities
    ├── DateHelper.ts
    └── ValidationHelper.ts

The feature-based structure (also called vertical slices, module-per-feature, or package-by-feature) organizes code by business capability. All code related to a feature—controller, service, repository, models, tests—lives in a single directory.

Characteristic structure:

src/
├── orders/                      # Order feature
│   ├── OrderController.ts
│   ├── OrderService.ts
│   ├── OrderRepository.ts
│   ├── Order.ts
│   ├── CreateOrderDto.ts
│   ├── OrderResponseDto.ts
│   └── __tests__/
│       ├── OrderService.test.ts
│       └── OrderController.test.ts
├── products/                    # Product feature
│   ├── ProductController.ts
│   ├── ProductService.ts
│   ├── ProductRepository.ts
│   ├── Product.ts
│   └── __tests__/
│       └── ProductService.test.ts
├── users/                       # User feature
│   ├── UserController.ts
│   ├── UserService.ts
│   ├── UserRepository.ts
│   ├── User.ts
│   └── __tests__/
│       └── UserService.test.ts
└── shared/                      # Cross-cutting concerns
    ├── middleware/
    │   └── AuthMiddleware.ts
    └── utils/
        └── DateHelper.ts

Guidelines for feature decomposition:

Deciding what constitutes a feature is often the most challenging aspect of feature-based structure. Here are heuristics that help:

1. Bounded contexts — If you're using Domain-Driven Design, each bounded context is a natural feature boundary.

2. Lifecycle independence — Features that can be developed, deployed, or replaced independently deserve separate directories.

3. Team ownership — If different teams own different parts of the system, structure by team ownership.

4. Change frequency — Code that changes together should live together; use git history to identify clusters.

5. Domain language — Features often align with nouns that domain experts use: orders, customers, payments, shipments.

Real-world projects rarely fit neatly into pure layered or pure feature-based patterns. Most successful projects use hybrid structures that combine elements of both, tailored to their specific needs.

Pattern A: Features with Internal Layers

Top-level organization is by feature, but each feature internally follows a layered structure:

src/
├── orders/
│   ├── api/                 # HTTP layer for orders
│   │   └── OrderController.ts
│   ├── domain/              # Business logic for orders
│   │   ├── Order.ts
│   │   └── OrderService.ts
│   ├── infrastructure/      # Data access for orders
│   │   └── OrderRepository.ts
│   └── index.ts             # Public exports for this feature
├── products/
│   ├── api/
│   ├── domain/
│   └── infrastructure/
└── shared/
    ├── kernel/              # Shared domain concepts
    └── infrastructure/      # Shared technical concerns

Pattern B: Core vs. Features

Separate the stable core domain from frequently changing features:

src/
├── core/                    # Stable domain model
│   ├── entities/
│   │   ├── Order.ts
│   │   └── Product.ts
│   ├── value-objects/
│   │   ├── Money.ts
│   │   └── Address.ts
│   └── domain-services/
│       └── PricingEngine.ts
├── features/                # Use cases and API
│   ├── checkout/
│   ├── catalog/
│   └── user-management/
└── infrastructure/          # Technical implementations
    ├── database/
    ├── messaging/
    └── external-services/

Pattern C: Hexagonal/Ports and Adapters Layout

Aligns structure with hexagonal architecture, separating the domain from infrastructure adapters:

src/
├── domain/                  # Pure business logic (no dependencies)
│   ├── orders/
│   │   ├── Order.ts
│   │   ├── OrderService.ts
│   │   └── OrderRepository.ts  # Interface only
│   └── products/
├── application/             # Use cases, orchestration
│   ├── PlaceOrderUseCase.ts
│   └── ListProductsUseCase.ts
├── adapters/                # Implementation of ports
│   ├── inbound/             # Driving adapters (API, CLI, etc.)
│   │   ├── http/
│   │   │   └── OrderController.ts
│   │   └── graphql/
│   │       └── OrderResolver.ts
│   └── outbound/            # Driven adapters (DB, external services)
│       ├── persistence/
│       │   └── PostgresOrderRepository.ts
│       └── messaging/
│           └── RabbitMQEventPublisher.ts
└── config/                  # Dependency injection, bootstrapping
    └── container.ts

Regardless of your organizational pattern, certain directories appear in virtually every well-structured project. Understanding their purpose helps you apply them consistently.

Test organization is a structural decision that significantly impacts development workflow. The two primary approaches—co-located tests and separate test directories—each have distinct advantages.

Hybrid approach for different test types:

Many projects use different strategies for different test categories:

src/
├── orders/
│   ├── OrderService.ts
│   ├── OrderService.test.ts       # Unit tests (co-located)
│   └── ...
tests/
├── integration/                    # Integration tests (separate)
│   └── orders/
│       └── OrderWorkflow.test.ts
├── e2e/                            # End-to-end tests (separate)
│   └── checkout.e2e.ts
└── fixtures/                       # Shared test data
    └── orders.fixtures.ts

This approach keeps fast, focused unit tests close to their subjects while housing slower, broader tests in a separate location.

Project structure is not static. As systems grow, the optimal structure often changes. Understanding this evolution helps you plan for growth without over-engineering at the start.

Signs that restructuring is needed:

• Developers frequently ask "where does this code go?"
• File counts in directories exceed 20-30 files
• Working on a feature requires touching more than 5 directories
• New developers take weeks to understand the codebase
• Team members organize code differently in different parts of the project
• Git merge conflicts happen frequently in the same areas

Making structural changes safely:

1. Document the target state — Before changing anything, write down what the new structure should look like and why.

2. Move incrementally — Restructure one feature or module at a time, not the entire codebase at once.

3. Update tooling — Ensure build configurations, linting rules, and IDE settings support the new structure.

4. Re-export for compatibility — Use barrel files (index.ts) to maintain existing import paths during transition.

5. Communicate continuously — Keep the team informed about structural changes and the rationale.

Let's trace how a real project might evolve its structure from startup to scale, making the principles concrete.

Phase 1: MVP (3 months, 2 developers, 30 files)

src/
├── controllers/
│   ├── ProductController.ts
│   └── OrderController.ts
├── services/
│   ├── ProductService.ts
│   └── OrderService.ts
├── models/
│   ├── Product.ts
│   └── Order.ts
└── db.ts

Simple layered structure works well. The team knows every file, there's minimal navigation overhead, and the focus is on shipping features quickly.

Phase 2: Product-Market Fit (18 months, 8 developers, 200 files)

The layered directories have grown large. Services has 30+ files. New developers struggle to find code. Features are intertwined.

src/
├── catalog/                      # Product catalog feature
│   ├── ProductController.ts
│   ├── ProductService.ts
│   ├── Product.ts
│   ├── Category.ts
│   └── CategoryService.ts
├── checkout/                     # Checkout feature
│   ├── CartController.ts
│   ├── CartService.ts
│   ├── Cart.ts
│   ├── OrderController.ts
│   ├── OrderService.ts
│   └── Order.ts
├── payments/                     # Payment integration
│   ├── PaymentController.ts
│   ├── PaymentService.ts
│   └── PaymentGateway.ts
├── users/                        # User management
│   ├── UserController.ts
│   ├── UserService.ts
│   └── User.ts
└── shared/
    ├── middleware/
    ├── utils/
    └── types/

The restructuring took 2 weeks of dedicated effort. Import paths changed across 150 files. But the result: clear feature ownership, reduced merge conflicts, faster onboarding.

Phase 3: Scale (4 years, 40 developers, 2000+ files)

The monolith is now too large for a single team to understand. Features need independent deployment. The decision: split into packages within a monorepo.

packages/
├── catalog-service/              # Independent deployable
│   ├── src/
│   │   ├── domain/
│   │   ├── application/
│   │   └── infrastructure/
│   ├── tests/
│   └── package.json
├── checkout-service/
│   ├── src/
│   │   ├── domain/
│   │   ├── application/
│   │   └── infrastructure/
│   ├── tests/
│   └── package.json
├── shared-kernel/                # Shared domain concepts
│   ├── src/
│   └── package.json
└── infrastructure-common/        # Shared infrastructure
    ├── src/
    └── package.json

Each package has its own internal structure (hexagonal in this case). Shared code is extracted to dedicated packages. Teams own packages and deploy independently.

We've covered extensive ground on project structure. Let's consolidate the essential takeaways:

What's next:

Now that we understand how to organize files and directories at the project level, the next page dives into package organization—how to group related components into coherent modules, manage dependencies between packages, and establish clear public APIs for each module.