Clean Architecture

Understanding the principles of Clean Architecture is essential, but translating those principles into a concrete project structure is where the rubber meets the road. How do you organize folders? What goes where? How do you enforce the Dependency Rule at the file system level?

In this final page of the Clean Architecture module, we bridge theory and practice. We'll examine multiple approaches to structuring Clean Architecture projects, discuss trade-offs between them, and provide concrete templates you can adapt to your own projects.

There are two fundamental approaches to organizing a Clean Architecture project:

Layer-First Organization:

Folders represent architectural layers, with features spread across them:

src/
├── entities/
│   ├── account.ts
│   ├── order.ts
│   └── user.ts
├── use-cases/
│   ├── transfer-funds.ts
│   ├── place-order.ts
│   └── register-user.ts
├── adapters/
│   ├── controllers/
│   ├── repositories/
│   └── gateways/
└── frameworks/
    ├── express-app.ts
    └── database.ts

Feature-First Organization:

Folders represent features, with layers inside each:

src/
├── accounts/
│   ├── entities/
│   ├── use-cases/
│   ├── adapters/
│   └── routes.ts
├── orders/
│   ├── entities/
│   ├── use-cases/
│   ├── adapters/
│   └── routes.ts
└── shared/
    ├── infrastructure/
    └── common/

Based on extensive experience with Clean Architecture projects, here is a recommended structure that balances all concerns:

src/
├── core/                        # The inner circles
│   ├── entities/                # Enterprise business rules
│   │   ├── account/
│   │   │   ├── account.ts
│   │   │   ├── account.test.ts
│   │   │   └── money.ts         # Value objects
│   │   ├── order/
│   │   │   ├── order.ts
│   │   │   ├── order-item.ts
│   │   │   └── order.test.ts
│   │   └── shared/
│   │       ├── entity-base.ts
│   │       └── value-object.ts
│   │
│   └── use-cases/               # Application business rules
│       ├── accounts/
│       │   ├── transfer-funds/
│       │   │   ├── transfer-funds.ts
│       │   │   ├── transfer-funds.test.ts
│       │   │   └── index.ts
│       │   └── ports/           # Abstractions needed by this domain
│       │       ├── account-repository.ts
│       │       └── notification-service.ts
│       └── orders/
│           ├── place-order/
│           │   ├── place-order.ts
│           │   └── place-order.test.ts
│           └── ports/
│               └── order-repository.ts
│
├── adapters/                    # Interface adapters
│   ├── controllers/             # HTTP controllers
│   │   ├── accounts/
│   │   │   ├── transfer-controller.ts
│   │   │   └── balance-controller.ts
│   │   └── orders/
│   │       └── order-controller.ts
│   ├── repositories/            # Database implementations
│   │   ├── postgres/
│   │   │   ├── account-repository.ts
│   │   │   └── order-repository.ts
│   │   └── in-memory/           # For testing
│   │       ├── account-repository.ts
│   │       └── order-repository.ts
│   ├── gateways/                # External service implementations
│   │   ├── stripe-payment-gateway.ts
│   │   └── sendgrid-email-service.ts
│   └── presenters/              # Output formatters
│       ├── json/
│       └── html/
│
├── infrastructure/              # Frameworks & drivers
│   ├── http/
│   │   ├── express-app.ts
│   │   ├── routes.ts
│   │   └── middleware/
│   ├── database/
│   │   ├── connection.ts
│   │   └── migrations/
│   ├── config/
│   │   └── index.ts
│   └── container/
│       └── index.ts             # Composition root
│
├── main.ts                      # Application entry point
└── types/                       # Shared type definitions
    └── index.ts

Folder structure alone doesn't enforce the Dependency Rule. Developers under pressure can still import from the wrong place. Here are concrete mechanisms for enforcement:

1. ESLint Import Restrictions

2. TypeScript Path Aliases

Path aliases make imports cleaner and can help enforce boundaries by making wrong imports more obvious:

Now imports look like:

// In a use-case - ALLOWED
import { Account } from '@entities/account';

// In a use-case - FORBIDDEN (would trigger ESLint error)
import { Pool } from '@infrastructure/database';

3. Architectural Fitness Functions (CI/CD)

Automate architecture verification in your build pipeline:

The Composition Root is the single location where all components are assembled. It's the only place that knows about all concrete implementations. Everything else works with abstractions.

Why One Place?

Centralizing composition provides:

• Single source of truth for wiring
• Easy to swap implementations (e.g., for testing)
• Clear understanding of all dependencies
• Isolation of configuration logic

Consistent naming helps developers quickly understand what a file contains and which layer it belongs to. Here are recommended conventions:

Entities (core/entities/)

• Named after domain concepts: Account, Order, User
• Value objects are similarly named: Money, Email, Address
• No prefixes or suffixes (they are the concepts)

Use Cases (core/use-cases/)

• Named as verb phrases: TransferFunds, PlaceOrder, RegisterUser
• One class per file, file name matches class name
• Input/Output DTOs named with suffix: TransferFundsInput, TransferFundsOutput

Ports (core/use-cases/*/ports/)

• Named after capability + "Repository" or "Service" or "Gateway":
  • AccountRepository, OrderRepository
  • NotificationService, PaymentGateway

Adapters (adapters/)

• Controllers: [Feature]Controller - TransferController, OrderController
• Repository implementations: [Technology][Entity]Repository - PostgresAccountRepository
• Gateway implementations: [Provider][Capability] - StripePaymentGateway, SendGridEmailService

Infrastructure (infrastructure/)

• Descriptive of technical concern: express-app.ts, database.ts, routes.ts

Clean Architecture naturally supports a layered testing strategy that aligns with the testing pyramid:

Unit Tests: Entities and Use Cases

The core layers are tested in complete isolation. No database, no HTTP, no external services. Tests run in milliseconds.

Integration Tests: Adapters

Adapter tests verify that implementations correctly interact with their external systems. These tests may require a running database or mock servers, but business logic is not re-tested here.

describe('PostgresAccountRepository', () => {
    let pool: Pool;
    let repository: PostgresAccountRepository;
    
    beforeAll(async () => {
        pool = new Pool({ connectionString: process.env.TEST_DATABASE_URL });
        await pool.query('DELETE FROM accounts');
    });
    
    beforeEach(() => {
        repository = new PostgresAccountRepository(pool);
    });
    
    test('should save and retrieve account', async () => {
        const account = new Account('test-1', 'owner-1', 100, 'checking');
        await repository.save(account);
        
        const retrieved = await repository.findById('test-1');
        expect(retrieved?.balance).toBe(100);
    });
});

End-to-End Tests: Full System

E2E tests verify the entire stack—from HTTP request to database and back. These are the slowest but catch integration issues between layers.

describe('Transfer API', () => {
    test('POST /api/transfers should transfer funds', async () => {
        // Setup test accounts in database
        await setupTestAccounts();
        
        const response = await request(app)
            .post('/api/transfers')
            .send({
                from_account: 'test-account-a',
                to_account: 'test-account-b',
                amount: 50,
                currency: 'USD',
            });
        
        expect(response.status).toBe(200);
        expect(response.body.data.source_balance).toBe(50);
    });
});

Implementing Clean Architecture in production involves practical considerations beyond the ideal structure:

Pragmatic Trade-offs

• Not every entity needs its own file: For small value objects, grouping related ones is acceptable.
• Simple CRUD doesn't need use cases: For pure CRUD operations with no business logic, you might go directly from controller to repository. Add use cases when logic appears.
• Shared DTOs are acceptable: If the HTTP DTO matches the use case DTO exactly, don't create redundant types.

Performance Considerations

• Entity mapping has overhead: Converting between database models and domain entities has a cost. For high-throughput read paths, consider read models that bypass the domain.
• Use case per request is fine: Creating use case instances per request is acceptable. They're lightweight objects.

Team Considerations

• Onboarding takes time: New team members need to understand the architecture. Document it clearly and include architecture tests that explain violations.
• Consistency is more important than perfection: It's better to have a consistently applied 80% clean architecture than an inconsistent 100% clean architecture.

Most teams don't start with Clean Architecture—they migrate to it. Here's a proven approach:

Phase 1: Identify the Core

Find the most important business logic. What are the key entities? What are the critical use cases? These are candidates for extraction.

Phase 2: Extract Entities

Create plain domain objects without framework dependencies. Initially, they might just wrap existing models:

// Before: ORM-coupled entity
@Entity()
class Account {
    @PrimaryGeneratedColumn()
    id: string;
    // ... ORM stuff mixed with domain logic
}

// After: Separate domain entity
class Account {
    constructor(public readonly id: string, ...) {}
    // Pure domain logic
}

// Plus: ORM model in adapter layer
@Entity()
class AccountModel {
    // ORM stuff only, no domain logic
}

Phase 3: Extract Use Cases

Pull business logic out of controllers into dedicated use cases. Define ports for dependencies:

// Before: Logic in controller
app.post('/transfer', async (req, res) => {
    const source = await db.query('SELECT ...');
    const dest = await db.query('SELECT ...');
    // ... 50 lines of business logic ...
    res.json({ success: true });
});

// After: Controller calls use case
app.post('/transfer', async (req, res) => {
    const result = await transferFunds.execute({
        sourceAccountId: req.body.from,
        destinationAccountId: req.body.to,
        amount: req.body.amount,
    });
    res.json(result);
});

Phase 4: Create Adapters

Implement the ports defined by use cases. This often means wrapping existing database code:

class PostgresAccountRepository implements AccountRepository {
    async findById(id: string): Promise<Account | null> {
        const row = await existingQueryFunction(id);
        return row ? new Account(row.id, row.balance, ...) : null;
    }
}

Phase 5: Wire Up

Create the composition root. Start with manual wiring; add a DI container if needed.

Phase 6: Add Enforcement

Add ESLint rules and architecture tests. Enforce boundaries going forward.

We've covered the practical implementation of Clean Architecture—how to organize projects, enforce boundaries, and apply the patterns in real-world contexts. Let's consolidate:

Module Complete:

You've now completed the Clean Architecture module. You understand its origins and philosophy, the Dependency Rule, the four layers in detail, and practical implementation patterns. You're equipped to implement Clean Architecture in new projects or migrate existing projects toward these principles.