architecture

Clean Architecture Rules

Layer Structure

src/
├── domain/           # Core business logic (PURE)
├── application/      # Use cases, orchestration
├── infrastructure/   # External services, DB
└── presentation/     # HTTP, API, UI

Dependency Rules (CRITICAL)

Presentation → Application → Domain
                    ↓
              Infrastructure

• Domain has NO external dependencies
• Application depends only on Domain
• Infrastructure implements Domain interfaces
• Presentation calls Application use cases

Domain Layer

// Entity - pure business logic
export class User {
  private constructor(private props: UserProps) {}

  static create(props: CreateUserProps): User {
    // Validation and business rules
    return new User({ ...props, id: generateId() });
  }

  // Business methods
  deactivate(): User {
    if (!this.isActive) throw new Error('Already inactive');
    return new User({ ...this.props, status: 'inactive' });
  }
}

// Repository interface (port)
export interface UserRepository {
  findById(id: string): Promise<User | null>;
  save(user: User): Promise<User>;
}

Application Layer

// Use case - orchestrates domain logic
export class CreateUserUseCase {
  constructor(
    private userRepo: UserRepository,
    private emailService: EmailService,
  ) {}

  async execute(input: CreateUserInput): Promise<CreateUserOutput> {
    const user = User.create(input);
    await this.userRepo.save(user);
    await this.emailService.sendWelcome(user.email);
    return { id: user.id };
  }
}

Infrastructure Layer

// Repository implementation (adapter)
export class PrismaUserRepository implements UserRepository {
  constructor(private prisma: PrismaClient) {}

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

Presentation Layer

// Controller/Route - thin, delegates to use case
router.post('/users', async (req, res) => {
  const result = await createUserUseCase.execute(req.body);
  res.status(201).json(result);
});