elegant-architecture

name	elegant-architecture
description	Guides clean architecture design with strict 200-line file limits. Use when starting new features, refactoring large files, or planning module structure. Enforces modular design and real testing.

Elegant Architecture

Core Principles

• 200-line limit — No file exceeds 200 lines of code
• Split when exceeded — Convert to folder or multiple files
• Plan first, code later — Design architecture before implementation
• Single responsibility — Each module does one thing well
• Real tests only — No mocks, test actual behavior

Execution Flow

1. Analyze Requirements

Before writing any code:
- List all features/functionalities needed
- Estimate code volume for each module
- Identify shared components
- Map dependencies between modules

2. Design File Structure

When estimated lines > 200:
- Convert file to folder with index
- Split by sub-functionality
- Extract shared utilities

Example transformation:

# Before (user.ts - 400+ lines)
user.ts

# After (user/ folder)
user/
├── index.ts        # Public exports
├── types.ts        # Interfaces, types
├── validation.ts   # Input validation
├── repository.ts   # Data access
└── service.ts      # Business logic

3. Define Interfaces First

// Define contracts before implementation
interface UserService {
  create(input: CreateUserInput): Promise<User>;
  findById(id: string): Promise<User | null>;
  update(id: string, input: UpdateUserInput): Promise<User>;
  delete(id: string): Promise<void>;
}

interface UserRepository {
  save(user: User): Promise<User>;
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  delete(id: string): Promise<void>;
}

4. Implement Incrementally

For each module:
1. Create type definitions
2. Implement core logic
3. Add error handling
4. Write tests
5. Verify line count < 200

5. Test Without Mocks

// ❌ Avoid: Mock everything
const mockRepo = jest.fn();
const service = new UserService(mockRepo);

// ✅ Prefer: Real implementations
const testDb = createTestDatabase();
const repo = new UserRepository(testDb);
const service = new UserService(repo);

// Test actual behavior
const user = await service.create({ email: '[e-mail]' });
const found = await service.findById(user.id);
expect(found).toEqual(user);

Design Patterns

Modular Design

src/
├── modules/
│   ├── auth/
│   │   ├── index.ts
│   │   ├── types.ts
│   │   ├── service.ts
│   │   └── middleware.ts
│   ├── user/
│   │   ├── index.ts
│   │   ├── types.ts
│   │   ├── service.ts
│   │   └── repository.ts
│   └── order/
│       ├── index.ts
│       ├── types.ts
│       ├── service.ts
│       └── repository.ts
├── shared/
│   ├── database/
│   ├── errors/
│   └── utils/
└── index.ts

Dependency Injection

// Decouple components via constructor injection
class OrderService {
  constructor(
    private readonly orderRepo: OrderRepository,
    private readonly userService: UserService,
    private readonly paymentGateway: PaymentGateway
  ) {}

  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
    const user = await this.userService.findById(userId);
    if (!user) throw new NotFoundError('User', userId);

    const order = Order.create(user, items);
    await this.paymentGateway.charge(user, order.total);
    return this.orderRepo.save(order);
  }
}

// Wire up in composition root
const orderService = new OrderService(
  new PostgresOrderRepository(db),
  new UserService(userRepo),
  new StripePaymentGateway(stripeClient)
);

Factory Pattern

// Complex object creation
class NotificationFactory {
  create(type: NotificationType, data: NotificationData): Notification {
    switch (type) {
      case 'email':
        return new EmailNotification(data, this.emailClient);
      case 'sms':
        return new SmsNotification(data, this.smsClient);
      case 'push':
        return new PushNotification(data, this.pushClient);
      default:
        throw new Error(`Unknown notification type: ${type}`);
    }
  }
}

Strategy Pattern

// Replaceable algorithms
interface PricingStrategy {
  calculate(order: Order): Money;
}

class StandardPricing implements PricingStrategy {
  calculate(order: Order): Money {
    return order.items.reduce((sum, item) => sum.add(item.price), Money.zero());
  }
}

class DiscountPricing implements PricingStrategy {
  constructor(private readonly discount: Percentage) {}

  calculate(order: Order): Money {
    const standard = new StandardPricing().calculate(order);
    return standard.subtract(standard.multiply(this.discount));
  }
}

class OrderProcessor {
  constructor(private pricing: PricingStrategy) {}

  setPricing(strategy: PricingStrategy) {
    this.pricing = strategy;
  }

  process(order: Order): ProcessedOrder {
    const total = this.pricing.calculate(order);
    return { ...order, total };
  }
}

File Splitting Guidelines

When to Split

Indicator	Action
File > 200 lines	Split immediately
File > 150 lines	Plan split
3+ distinct responsibilities	Split by responsibility
Shared types growing	Extract to types.ts
Utility functions accumulating	Extract to utils.ts

How to Split

1. Identify logical boundaries
2. Create folder with same name as file
3. Move related code to separate files
4. Create index.ts for public exports
5. Update imports in dependent files

Naming Conventions

module/
├── index.ts          # Public API exports
├── types.ts          # Interfaces, types, enums
├── constants.ts      # Configuration, magic values
├── utils.ts          # Helper functions
├── service.ts        # Business logic
├── repository.ts     # Data access
├── validation.ts     # Input validation
└── errors.ts         # Custom errors

Architecture Checklist

## Pre-Implementation
- [ ] Requirements analyzed
- [ ] Code volume estimated
- [ ] File structure designed
- [ ] Interfaces defined
- [ ] Dependencies mapped

## Implementation
- [ ] Each file < 200 lines
- [ ] Single responsibility per module
- [ ] Dependencies injected
- [ ] Error handling complete
- [ ] No hardcoded values

## Testing
- [ ] Real implementations used
- [ ] No mocks for core logic
- [ ] Edge cases covered
- [ ] Integration tests exist

## Review
- [ ] Architecture documented
- [ ] Public APIs clear
- [ ] No circular dependencies
- [ ] Easy to extend

Anti-Patterns to Avoid

❌ God files (500+ lines doing everything)
❌ Mocking everything in tests
❌ Coding before planning
❌ Tight coupling between modules
❌ Hardcoded configuration
❌ Circular dependencies
❌ Unclear module boundaries

Key Principles

1. Measure twice, cut once — Plan architecture before coding
2. Small is beautiful — 200 lines max, no exceptions
3. Test reality — Real tests catch real bugs
4. Inject dependencies — Loose coupling, easy testing
5. Single purpose — One reason to change per module