Add Task 4.0: Integrated Refactoring Exercise (11.2.5)

[Copilot]

Implements comprehensive refactoring exercise synthesizing Repository, Service Layer, and Strategy patterns. Students transform a deliberately flawed e-commerce system while preserving behavior through 37 tests.

Implementation

Starter Application - Authentic anti-patterns for teaching

• 450-line God Object (routes.ts) with 7+ SOLID violations
• if/else chains for payment/shipping (violates OCP)
• Direct SQLite coupling (violates DIP)
• TypeScript/Express/SQLite stack with comprehensive test coverage

Solution Application - Clean architecture demonstrating

• Strategy Pattern: Eliminates type-checking with IPaymentStrategy/IShippingStrategy interfaces
• Repository Pattern: Abstracts data access with IOrderRepository/IProductRepository
• Service Layer: Orchestrates business logic via OrderService
• Factory Pattern: Creates strategies dynamically
• Dependency Injection: Explicit wiring in index.ts

Documentation & Analysis

• Analysis guide with specific line numbers for each SOLID violation
• 5-phase student workflow: Analysis → Planning → Implementation → Verification → Comparison
• Metrics: 450 lines → <150 across 20+ files, adding Apple Pay: 3 files → 1 file

Behavior Preservation

Identical test suite runs against both implementations:

// Same tests validate business rules in starter and solution
describe('Payment Processing', () => {
  it('should apply 3% fee for credit card payments', async () => {
    const response = await request(app)
      .post('/api/orders')
      .send({ payment_type: 'credit_card', ... });
    expect(response.body.payment_fee).toBe(0.90); // For $29.99 subtotal
  });
});

37/37 tests pass in both versions, proving refactoring preserves behavior.

Files

• docs/11-application-development/11.2.5-refactoring-exercise.md - Main exercise documentation
• examples/ch11/refactoring-exercise/starter/ - Flawed implementation (14 files)
• examples/ch11/refactoring-exercise/solution/ - Refactored implementation (32 files)
• examples/ch11/refactoring-exercise/analysis-guide.md - SOLID violation analysis
• examples/ch11/refactoring-exercise/research-notes.md - OSS evaluation justification

Navigation updated in docs/_sidebar.md.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Task 4.0: Integrated Refactoring Exercise (11.2.5)</issue_title>
<issue_description># GitHub Issue: Task 4.0 - Integrated Refactoring Exercise (11.2.5)

🎯 Task Overview

Task ID: 4.0
Parent Spec: docs/specs/01-spec-design-patterns-section/01-spec-design-patterns-section.md
Status: Ready for Implementation
Estimated Time: 8-12 hours

This task implements a comprehensive refactoring exercise (11.2.5) that synthesizes Repository Pattern, Service Layer, and Strategy Pattern. Students refactor a TypeScript e-commerce order processing system with intentional anti-patterns into clean, SOLID-compliant architecture.

Key Deliverables:

• Starter application with deliberate design flaws (God Object, if/else chains, tight coupling)
• Comprehensive behavior-based test suite (passes with both starter and solution)
• Analysis guide for identifying SOLID violations
• Reference solution demonstrating pattern applications
• Complete exercise documentation with phase-by-phase instructions

---

📋 Specification Context

Project Overview

This specification defines the remaining Design Patterns subsections for Chapter 11 (Application Development) of the DevOps Bootcamp. Task 4.0 is the capstone exercise that synthesizes learning from Data Layer Patterns (11.2.2), Business Logic Patterns (11.2.3), Classical GoF Patterns (11.2.4), and SOLID Principles (11.2.1).

User Story

US-5: Applying Multiple Patterns in Realistic Refactoring
As a bootcamp apprentice learning design patterns, I want to refactor a poorly-structured application using Repository, Service Layer, and Strategy patterns so that I can understand how patterns work together to solve real architectural problems.

US-5.1: Identifying Anti-Patterns
As a developer learning SOLID principles, I want guidance on identifying code smells and violations so that I can recognize similar issues in production codebases.

US-5.2: Preserving Behavior Through Refactoring
As a developer refactoring legacy code, I want comprehensive tests that validate behavior so that I can safely restructure code without breaking functionality.

Functional Requirements

ID	Requirement
U5-FR1	The system shall provide starter application code with deliberately introduced design issues including: God Object pattern, if/else chains for payment/shipping, direct database queries, and SOLID violations (SRP, OCP, DIP)
U5-FR2	The application shall implement e-commerce order processing domain with realistic entities: Order, OrderItem, Product, Customer, Payment (CreditCard/PayPal/Bitcoin), Shipping (Standard/Express/Overnight), and Inventory
U5-FR3	The system shall include comprehensive automated tests using Jest and Supertest that validate business behavior and must pass before and after refactoring without modification
U5-FR4	The system shall provide analysis guide (analysis-guide.md) helping students identify specific anti-patterns with line numbers, metrics collection, SOLID violations, and phase-by-phase refactoring roadmap
U5-FR5	The system shall include instructions for students to create refactoring plan specifying interfaces to define, patterns to apply, and implementation order
U5-FR6	The system shall guide students to apply Strategy Pattern for payment/shipping (eliminates if/else chains), Repository Pattern for data access (abstracts SQLite), and Service Layer for business logic (separates from HTTP)
U5-FR7	The system shall include git workflow guidelines with commit message templates documenting refactoring decisions and pattern applications
U5-FR8	The system shall provide reference solution showing refactored implementation with Strategy interfaces, Repository interfaces, Service classes, and thin HTTP layer
U5-FR9	The exercise shall be self-directed with students working in starter/ directory and comparing to solution/ directory
U5-FR10	The implementation shall document research decision to build custom application (vs. adapting OSS project) based on pedagogical control, licensing freedom, and integration with bootcamp conventions

---

✅ Acceptance Criteria (Proof Artifacts)

The following artifacts must exist and be verified for task completion:

• Documentation: docs/11-application-development/11.2.5-refactoring-exercise.md exists with complete instructions including front-matter, 5-phase structure (Analysis/Planning/Implementation/Verification/Comparison), setup steps, success criteria, and reflection questions
• Research Notes: examples/ch11/refactoring-exercise/research-notes.md documents OSS project evaluation and justification for building custom application
• Starter Application: examples/ch11/refactoring-exercise/starter/ contains TypeScript application with package.json, tsconfig.json, jest.config.js, src/routes.ts (450-line God Obj...

• Fixes Task 4.0: Integrated Refactoring Exercise (11.2.5) #825

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[HexSleeves]

Cleaned up for review:

• Merged master, resolved conflicts; reverted all repo-level config churn (.markdownlint.json, .markdownlintignore, root package.json/lock now match master) and fixed the 42 lint violations those disables were masking.
• Both example apps pass: starter 37/37, solution 37/37.

Open questions for reviewer:

1. The prerequisites link to 11.2.3 resolves once Add Business Logic Patterns documentation and TypeScript examples (11.2.3) #822 merges (merge order: Add Business Logic Patterns documentation and TypeScript examples (11.2.3) #822 → Add Classical Gang of Four Patterns documentation and multi-language examples #824 → this).
2. No quiz for 11.2.5 unlike siblings — intentional for a capstone exercise, or should one be added?
3. estReadingMinutes: 20 seems low for a 900-line, ~180-minute exercise (siblings are 45–120).