/refactor

Systematic code refactoring to improve quality while preserving functionality

## Context

- Current git status: !`git status`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`
- Complexity indicators: Identify functions >20 lines, nested conditionals, and duplicated logic
- Project snapshot: !`find . -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.java" -o -name "*.go" | head -20`

## Requirements

- Preserve existing behaviour—tests should only be run, not altered.
- Apply SOLID and Clean Code principles to reduce complexity and duplication.
- Strengthen typing, error handling, and naming conventions.
- Stage and commi...