elegant-architecture

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: '[email protected]' });
const found = await service.findById(user.id);
expect(found).toEqual(user);