clean-architecture

Clean Architecture Skill

Directory Structure

Organize by feature/domain, NOT by type:

src/
├── modules/
│   ├── users/
│   │   ├── domain/           # Entities, value objects
│   │   ├── application/      # Use cases, DTOs
│   │   ├── infrastructure/   # Repositories, adapters
│   │   └── presentation/     # Controllers
│   └── orders/
├── shared/
│   ├── domain/
│   ├── infrastructure/
│   └── utils/
└── main.ts

SOLID Principles

S - Single Responsibility: One class = one purpose O - Open/Closed: Extend via interfaces, not modification L - Liskov Substitution: Subtypes replaceable for base types I - Interface Segregation: Many small interfaces > one large D - Dependency Inversion: Depend on abstractions

Layer Rules

Domain (Core)

• Entities, Value Objects, Domain Services
• ZERO external dependencies

export class User {
  static create(props: CreateUserProps): User {
    return new User(generateId(), new Email(props.email), UserStatus.PENDING);
  }

  activate(): void {
    if (this._status !== UserStatus.PENDING) {
      throw new DomainError('Cannot activate');
    }
    this._status = UserStatus.ACTIVE;
  }
}

Application

• Use Cases, DTOs, Port interfaces
• Depends only on Domain

export class CreateUserUseCase {
  constructor(
    private readonly userRepository: IUserRepository,
    private readonly emailService: IEmailService
  ) {}

  async execute(input: CreateUserInput): Promise<CreateUserOutput> {
    const existing = await this.userRepository.findByEmail(input.email);
    if (existing) throw new UserAlreadyExistsError(input.email);

    const user = User.create(input);
    await this.userRepository.save(user);
    return { id: user.id };
  }
}

Infrastructure

• Repository implementations, External adapters
• Implements Application interfaces

export class PrismaUserRepository implements IUserRepository {
  constructor(private readonly prisma: PrismaClient) {}

  async findByEmail(email: string): Promise<User | null> {
    const data = await this.prisma.user.findUnique({ where: { email } });
    return data ? UserMapper.toDomain(data) : null;
  }
}