Task 4.0: Integrated Refactoring Exercise (11.2.5)

[jburns24]

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 Object), database.ts, types.ts, and schema.sql
• Behavior-Based Tests: examples/ch11/refactoring-exercise/starter/tests/ contains order-creation.test.ts, payment.test.ts, inventory.test.ts that validate business outcomes (not implementation)
• Starter README: examples/ch11/refactoring-exercise/starter/README.md includes setup instructions, npm commands, testing steps, and Your Task section
• Analysis Guide: examples/ch11/refactoring-exercise/analysis-guide.md includes metrics collection, SOLID violation checklist with line numbers, code smell identification, testability assessment, and refactoring roadmap
• Solution Application: examples/ch11/refactoring-exercise/solution/ contains refactored implementation with strategies/payment/, strategies/shipping/, repositories/, services/, routes/, and factories/
• Solution README: examples/ch11/refactoring-exercise/solution/README.md explains architecture changes, pattern applications (Strategy/Repository/Service Layer), and before/after comparisons
• CLI: Starter Tests Pass: cd starter && npm test passes all tests demonstrating baseline functionality
• CLI: Solution Tests Pass: cd solution && npm test passes all tests with same test files demonstrating behavior preservation
• Extension Test: Adding ApplePayPayment.ts in solution/ requires zero modifications to existing files demonstrating Open/Closed Principle
• Metrics Documented: Solution README includes before/after metrics (routes.ts: 450 lines → 20 lines, files: 4 → 20+, largest function: 100 lines → <30 lines)

---

📝 Sub-tasks

Research and Decision Tasks

• 4.1 Research open-source e-commerce TypeScript/Node.js applications evaluating 3-5 candidates using scoring rubric: Technical Fit (40pts: TypeScript native, clear anti-patterns, 500-2000 LOC, testable), Educational Fit (30pts: readable, real-world scenarios, clear refactoring opportunities), Practical (30pts: permissive license, minimal dependencies, maintained)
• 4.2 Create examples/ch11/refactoring-exercise/research-notes.md documenting evaluated projects with GitHub URLs, anti-patterns identified, scoring, and final decision rationale (recommended: build custom application for pedagogical control, licensing freedom, and bootcamp integration)

Starter Application Tasks

• 4.3 Create starter application structure in examples/ch11/refactoring-exercise/starter/ with package.json (express, sqlite3, typescript, jest, supertest, ts-jest dependencies), tsconfig.json (strict mode), jest.config.js (ts-jest preset), schema.sql (products, customers, orders, order_items tables with seed data)
• 4.4 Create starter/src/ with index.ts (Express server setup), routes.ts (450-line God Object with all business logic), database.ts (SQLite connection), types.ts (Product, Customer, Order, OrderItem, CreateOrderRequest interfaces)
• 4.5 Implement anti-patterns in routes.ts: POST /orders handler with direct validation (lines 15-25), direct SQLite db.run() calls (lines 30-110), if/else chains for payment types - credit_card (3% fee), paypal (3.5% fee), bitcoin ($1.50 flat fee) (lines 50-70), if/else chains for shipping methods - standard ($5.99, 7 days), express ($12.99, 3 days), overnight ($24.99, 1 day) (lines 75-90), inventory decrement logic mixed with order creation (lines 95-110)
• 4.6 Create behavior-based test suite in starter/tests/ with order-creation.test.ts (POST /orders with valid data, total calculation verification, validation error cases), payment.test.ts (credit card 3% fee test, PayPal 3.5% fee test, Bitcoin $1.50 flat fee test, invalid payment type rejection), inventory.test.ts (insufficient stock rejection, stock decrement after order, multiple items in single order)
• 4.7 Create starter/README.md with sections: Overview (e-commerce order processing with intentional anti-patterns), Setup (npm install, npm run db:init, npm run dev), Running Tests (npm test), Testing API (curl example for POST /orders), Your Task (reference analysis-guide.md, follow refactoring roadmap), Success Criteria (tests pass, routes.ts <50 lines, can add Apple Pay with one file, can test without database)
• 4.8 Create analysis-guide.md with Step 1: Initial Assessment (metrics collection commands for LOC/function count, architecture diagram exercise), Step 2: SOLID Principle Violations (SRP checklist for routes.ts with 7+ reasons to change, OCP exercise for adding Apple Pay requiring modification, DIP assessment showing sqlite3.Database concrete dependency), Step 3: Code Smells (God Object checklist, if/else type checking locations, missing abstraction layers), Step 4: Testability Analysis (requirements for testing with Express server and SQLite), Step 5: Refactoring Roadmap (Phase 1: Interfaces, Phase 2: Strategies, Phase 3: Repositories, Phase 4: Service Layer, Phase 5: Simplify Routes), Step 6: Verification (after refactoring checklist with success metrics)

Reference Solution Tasks

• 4.9 Create solution directory structure in examples/ch11/refactoring-exercise/solution/ with src/strategies/payment/ (IPaymentStrategy.ts interface, CreditCardPayment.ts, PayPalPayment.ts, BitcoinPayment.ts implementations), src/strategies/shipping/ (IShippingStrategy.ts interface, StandardShipping.ts, ExpressShipping.ts, OvernightShipping.ts implementations)
• 4.10 Create Repository Pattern implementation in solution/src/repositories/ with IOrderRepository.ts (create, findById, addItems, updateStatus methods), OrderRepository.ts (SQLite implementation with Database injection), IProductRepository.ts (findById, updateStock, checkStock methods), ProductRepository.ts (SQLite implementation)
• 4.11 Create Service Layer in solution/src/services/ with ValidationService.ts (validateOrderRequest with business rule checks), InventoryService.ts (checkAvailability, decrementStock using ProductRepository), OrderService.ts (createOrder orchestrating validation, inventory, payment strategy, shipping strategy, repository operations)
• 4.12 Create Factory Pattern in solution/src/factories/ with PaymentStrategyFactory.ts (getStrategy method returning IPaymentStrategy, registerStrategy for extension), ShippingStrategyFactory.ts (getStrategy method returning IShippingStrategy)
• 4.13 Create thin HTTP layer in solution/src/routes/orderRoutes.ts (20-line file with single POST /orders handler that parses request, calls orderService.createOrder(), formats response, handles errors)
• 4.14 Create dependency injection wiring in solution/src/index.ts (instantiate Database, create repositories with db injection, create factories, create services with dependency injection, create routes with service injection, wire to Express app)
• 4.15 Copy test suite from starter to solution solution/tests/ (SAME test files: order-creation.test.ts, payment.test.ts, inventory.test.ts with NO modifications demonstrating behavior preservation)
• 4.16 Create solution/README.md with Architecture Overview (before: routes.ts → SQLite, after: routes → OrderService → Repositories/Strategies), Pattern Applications (Strategy Pattern: eliminates if/else chains, shows OCP with Apple Pay extension, Repository Pattern: abstracts data access, shows DIP with PostgreSQL swap example, Service Layer: separates concerns, shows SRP with testability), Before/After Metrics (routes.ts: 450 lines → 20 lines, largest function: 100 lines → <30 lines, files: 4 → 20+, to add Apple Pay: modify 3 files → create 1 file)

Documentation and Verification Tasks

• 4.17 Create docs/11-application-development/11.2.5-refactoring-exercise.md with front-matter (category: Software Development, estReadingMinutes: 20, exercises: [{name: Integrated Refactoring Exercise, description: Refactor e-commerce application using patterns, estMinutes: 180, technologies: [TypeScript, Design Patterns]}])
• 4.18 Write exercise documentation with Overview (synthesis of 11.2.2-11.2.4 patterns), Learning Objectives (identify SOLID violations, apply Repository/Service Layer/Strategy patterns, verify behavior preservation, measure refactoring success), Prerequisites (links to 11.2.1-11.2.4), Domain Description (e-commerce order processing features and starter architecture diagram)
• 4.19 Write Phase 1: Code Analysis section (Task 1.1: Complete analysis-guide.md with metrics and line numbers, Task 1.2: Draw architecture diagram showing dependencies, Task 1.3: Document changes required to add Apple Pay)
• 4.20 Write Phase 2: Planning Your Refactoring section (Task 2.1: Define interfaces for IPaymentStrategy, IShippingStrategy, IOrderRepository, IProductRepository, Task 2.2: Plan refactoring order with rationale, Task 2.3: Set up directory structure with mkdir commands)
• 4.21 Write Phase 3: Implementation section (Task 3.1-3.6: Step-by-step implementation of Strategy Pattern for payments/shipping, Repository Pattern for data access, Service Layer for business logic, thin routes, and dependency injection wiring with test-your-progress checkpoints)
• 4.22 Write Phase 4: Verification section (Task 4.1: Run tests and verify behavior preserved, Task 4.2: Compare before/after metrics, Task 4.3: Extension Test for adding Apple Pay, Task 4.4: Testability Assessment with unit test challenge)
• 4.23 Write Phase 5: Comparing Solutions section (Task 5.1: Review reference solution, Task 5.2: Compare architectures with diagrams, Task 5.3: Diff key files showing starter vs solution)
• 4.24 Add Git Workflow section (recommended commit strategy: 8 commits from initial to final, commit message guidelines with refactor: prefix, SOLID principles applied, patterns introduced, benefits, tests status)
• 4.25 Add Success Criteria checklist (tests pass, routes.ts <50 lines, can add Apple Pay with one file, can test OrderService without database, no if/else chains, business logic separated from data access and HTTP)
• 4.26 Add Reflection Questions section (5 questions: before vs after improvements, complexity trade-offs justification, real-world applications, pattern selection guidance, testing impact)
• 4.27 Add Additional Challenges section (Challenge 1: Add Apple Pay with 4% fee, Challenge 2: Add discount strategy system, Challenge 3: Swap to PostgreSQL by creating PostgresOrderRepository, Challenge 4: Add API versioning /api/v2/orders reusing OrderService)
• 4.28 Verify starter application: Run cd examples/ch11/refactoring-exercise/starter && npm install && npm test confirming all tests pass with exit code 0 demonstrating baseline functionality
• 4.29 Verify solution application: Run cd examples/ch11/refactoring-exercise/solution && npm install && npm test confirming all tests pass with same test files demonstrating behavior preservation and successful refactoring
• 4.30 Verify extension scenario: Create solution/src/strategies/payment/ApplePayPayment.ts implementing IPaymentStrategy with 4% fee, register in PaymentStrategyFactory, run tests confirming zero modifications to existing files required demonstrating Open/Closed Principle

---

📁 Relevant Files

Files to Create

Research & Analysis

• examples/ch11/refactoring-exercise/research-notes.md - OSS project evaluation and custom build decision rationale
• examples/ch11/refactoring-exercise/analysis-guide.md - Structured guide for identifying anti-patterns and SOLID violations with refactoring roadmap

Starter Application

• examples/ch11/refactoring-exercise/starter/package.json - Node.js dependencies and scripts
• examples/ch11/refactoring-exercise/starter/tsconfig.json - TypeScript configuration (strict mode)
• examples/ch11/refactoring-exercise/starter/jest.config.js - Jest testing configuration
• examples/ch11/refactoring-exercise/starter/schema.sql - SQLite database schema and seed data
• examples/ch11/refactoring-exercise/starter/README.md - Setup instructions and Your Task section
• examples/ch11/refactoring-exercise/starter/src/index.ts - Express server setup
• examples/ch11/refactoring-exercise/starter/src/routes.ts - God Object with all business logic (450 lines)
• examples/ch11/refactoring-exercise/starter/src/database.ts - SQLite connection setup
• examples/ch11/refactoring-exercise/starter/src/types.ts - TypeScript interfaces
• examples/ch11/refactoring-exercise/starter/tests/order-creation.test.ts - Order workflow tests
• examples/ch11/refactoring-exercise/starter/tests/payment.test.ts - Payment processing tests
• examples/ch11/refactoring-exercise/starter/tests/inventory.test.ts - Inventory management tests

Solution Application - Strategies

• examples/ch11/refactoring-exercise/solution/src/strategies/payment/IPaymentStrategy.ts - Payment strategy interface
• examples/ch11/refactoring-exercise/solution/src/strategies/payment/CreditCardPayment.ts - Credit card implementation (3% fee)
• examples/ch11/refactoring-exercise/solution/src/strategies/payment/PayPalPayment.ts - PayPal implementation (3.5% fee)
• examples/ch11/refactoring-exercise/solution/src/strategies/payment/BitcoinPayment.ts - Bitcoin implementation ($1.50 flat fee)
• examples/ch11/refactoring-exercise/solution/src/strategies/shipping/IShippingStrategy.ts - Shipping strategy interface
• examples/ch11/refactoring-exercise/solution/src/strategies/shipping/StandardShipping.ts - Standard shipping ($5.99, 7 days)
• examples/ch11/refactoring-exercise/solution/src/strategies/shipping/ExpressShipping.ts - Express shipping ($12.99, 3 days)
• examples/ch11/refactoring-exercise/solution/src/strategies/shipping/OvernightShipping.ts - Overnight shipping ($24.99, 1 day)

Solution Application - Repositories

• examples/ch11/refactoring-exercise/solution/src/repositories/IOrderRepository.ts - Order repository interface
• examples/ch11/refactoring-exercise/solution/src/repositories/OrderRepository.ts - SQLite order repository implementation
• examples/ch11/refactoring-exercise/solution/src/repositories/IProductRepository.ts - Product repository interface
• examples/ch11/refactoring-exercise/solution/src/repositories/ProductRepository.ts - SQLite product repository implementation

Solution Application - Services

• examples/ch11/refactoring-exercise/solution/src/services/OrderService.ts - Business logic orchestration
• examples/ch11/refactoring-exercise/solution/src/services/ValidationService.ts - Input validation
• examples/ch11/refactoring-exercise/solution/src/services/InventoryService.ts - Stock management

Solution Application - Factories & Infrastructure

• examples/ch11/refactoring-exercise/solution/src/factories/PaymentStrategyFactory.ts - Creates payment strategies
• examples/ch11/refactoring-exercise/solution/src/factories/ShippingStrategyFactory.ts - Creates shipping strategies
• examples/ch11/refactoring-exercise/solution/src/routes/orderRoutes.ts - Thin HTTP layer (20 lines)
• examples/ch11/refactoring-exercise/solution/src/index.ts - Dependency injection wiring
• examples/ch11/refactoring-exercise/solution/src/database.ts - SQLite connection
• examples/ch11/refactoring-exercise/solution/src/domain/types.ts - TypeScript interfaces
• examples/ch11/refactoring-exercise/solution/package.json - Same dependencies as starter
• examples/ch11/refactoring-exercise/solution/tsconfig.json - Same config as starter
• examples/ch11/refactoring-exercise/solution/jest.config.js - Same config as starter
• examples/ch11/refactoring-exercise/solution/schema.sql - Same schema as starter
• examples/ch11/refactoring-exercise/solution/README.md - Architecture explanation and pattern applications
• examples/ch11/refactoring-exercise/solution/tests/order-creation.test.ts - SAME tests as starter
• examples/ch11/refactoring-exercise/solution/tests/payment.test.ts - SAME tests as starter
• examples/ch11/refactoring-exercise/solution/tests/inventory.test.ts - SAME tests as starter

Documentation

• docs/11-application-development/11.2.5-refactoring-exercise.md - Main exercise documentation with 5-phase structure

Files to Reference

• docs/11-application-development/11.2.1-solid-principles.md - SOLID principles foundation (for cross-references)
• docs/11-application-development/11.2.2-data-layer-patterns.md - Repository Pattern coverage (Task 1.0)
• docs/11-application-development/11.2.3-business-logic-patterns.md - Service Layer Pattern coverage (Task 2.0)
• docs/11-application-development/11.2.4-classical-patterns.md - Strategy Pattern coverage (Task 3.0)
• examples/ch11/solid-exercises/exercise-1-srp/ - Example of existing refactoring exercise structure
• examples/ch11/example1/ - Example of "before" monolithic structure
• examples/ch11/example2/ - Example of "after" layered structure

---

🎓 Repository Standards

Code Example Standards

• Project Structure: Starter and solution are self-contained with package.json, tsconfig.json, jest.config.js, src/, tests/, README.md, .gitignore
• README Requirements: Include setup instructions, npm install/test/dev commands, curl examples, and clear success criteria
• Development Environment: Assume modern ARM-based macOS; avoid external service dependencies
• Database: Use SQLite for portability (no external database servers)
• TypeScript Standards: TypeScript 5.x with strict mode, Express 4.x, SQLite3, Jest with ts-jest
• Testing: Use Jest with Supertest for HTTP testing, behavior-based tests must pass with both starter and solution
• Anti-Pattern Authenticity: Starter code anti-patterns must reflect real-world code smells (God Object, if/else chains, tight coupling)

Documentation Standards

• Front-Matter: Include YAML metadata with category: Software Development, estReadingMinutes: 20, exercises with 180-minute estimate and TypeScript/Design Patterns technologies
• Technologies: Use TypeScript, Design Patterns, SQLite as technology tags
• Header Levels: Use H2 (##) for phase navigation (Phase 1: Analysis, Phase 2: Planning, etc.), H3 (###) for tasks within phases
• Code Examples: Use fenced code blocks with typescript/bash language tags, show before/after comparisons where appropriate
• Cross-References: Link to 11.2.1 (SOLID Principles), 11.2.2 (Repository Pattern), 11.2.3 (Service Layer), 11.2.4 (Strategy Pattern)
• Exercise Structure: Use task-based structure (Task 1.1, Task 1.2) with clear deliverables and checkpoints

Testing Standards

• Behavior-Based Testing: Tests must validate business outcomes, not implementation details
• Test Preservation: Exact same test files must work with both starter and solution demonstrating behavior preservation
• Coverage Areas: Order creation workflow, payment fee calculations (3 types), shipping cost calculations (3 methods), inventory management, validation errors
• Test Organization: Group by feature (order-creation.test.ts, payment.test.ts, inventory.test.ts), not by pattern
• Setup/Teardown: Use beforeEach to reset SQLite database ensuring test isolation

Pattern Application Standards

• Strategy Pattern: Must have interface (IPaymentStrategy, IShippingStrategy), 3+ concrete implementations, Factory for creation, demonstrate extension without modification (Apple Pay test)
• Repository Pattern: Must have interface (IOrderRepository, IProductRepository), SQLite implementation with database injection, demonstrate swappability in README
• Service Layer: Must orchestrate domain logic, use dependency injection for repositories/strategies, separate from HTTP concerns, demonstrate testability without Express
• Thin HTTP Layer: Routes must be <30 lines per handler, only handle request/response, delegate all logic to services

---

🔗 Related Documentation

• Full Spec: docs/specs/01-spec-design-patterns-section/01-spec-design-patterns-section.md
• Complete Task List: docs/specs/01-spec-design-patterns-section/01-tasks-design-patterns-section.md
• Project Overview: CLAUDE.md (repository root)
• Style Guide: STYLE.md (repository root)

---

🤖 AI Agent Instructions

Implementation Approach

1. Start with Research Documentation: Create research-notes.md documenting OSS evaluation and decision rationale for custom build
2. Build Starter Application First: Implement anti-patterns authentically - resist urge to write "good" code, make violations obvious
3. Write Behavior-Based Tests: Tests must validate outcomes that won't change during refactoring (total amounts, error messages, business rules)
4. Create Analysis Guide: Document specific line numbers for violations, provide structured approach for students
5. Implement Solution Incrementally: Build strategies first (easiest to test), then repositories, then services, then routes
6. Verify Test Preservation: Confirm exact same test files pass with both versions before proceeding
7. Document Pattern Applications: Solution README must clearly explain how each pattern solves specific starter problems

Quality Checklist

• Starter code has authentic anti-patterns from real production code (not contrived)
• routes.ts is genuinely 400-500 lines with God Object pattern
• if/else chains for payment/shipping are realistic (3+ options each)
• Tests validate business behavior, not implementation (no "should call OrderService.createOrder")
• All tests pass with starter: cd starter && npm test → exit 0
• All tests pass with solution: cd solution && npm test → exit 0
• Test files are identical in both versions (can diff to verify)
• analysis-guide.md has specific line numbers for violations (not generic)
• Solution demonstrates OCP: Can add Apple Pay by creating ONE file
• Solution demonstrates DIP: Can mock repositories for testing
• Solution demonstrates SRP: OrderService can be tested without Express
• Documentation follows 5-phase structure with clear tasks
• Front-matter includes 180-minute exercise estimate
• README files have working setup instructions
• Cross-references to 11.2.1-11.2.4 are accurate and helpful

Common Pitfalls to Avoid

• DON'T make starter code too obvious - anti-patterns should feel like "real" code
• DON'T write implementation-specific tests - they'll break during refactoring
• DON'T skip behavior verification - tests MUST pass with both versions
• DON'T make solution over-engineered - keep it educational, not enterprise-grade
• DON'T forget line numbers in analysis-guide.md - students need specific guidance
• DON'T skip the "why" - explain WHY each pattern solves specific problems
• DON'T create different test files - use EXACT same tests to prove behavior preservation
• DON'T forget metrics - before/after numbers demonstrate improvement

Dependencies

• Node.js 18+ (for native fetch, modern TypeScript)
• TypeScript 5.x
• Express 4.x (lightweight web framework)
• SQLite3 (embedded database)
• Jest + ts-jest (testing)
• Supertest (HTTP testing)
• No external services required (fully self-contained)

Success Criteria

This task is complete when:

1. All 30 sub-tasks are checked off
2. All proof artifacts exist and are verified
3. npm test passes in both starter/ and solution/ directories
4. Test files are identical in both directories (can diff to confirm)
5. Adding Apple Pay requires creating only one new file (no modifications)
6. analysis-guide.md has specific line numbers for all violations
7. Documentation follows bootcamp conventions with proper front-matter
8. Solution README includes before/after architecture diagrams
9. Extension test (Apple Pay) is documented and verified
10. Metrics demonstrate measurable improvement (450 lines → 20 lines for routes)

---

📋 How to Create This Issue

Option 1: Using GitHub CLI (Recommended)

gh issue create --repo liatrio/devops-bootcamp \
  --title "Task 4.0: Integrated Refactoring Exercise (11.2.5)" \
  --body-file docs/specs/01-spec-design-patterns-section/task-4.0-github-issue.md \
  --label "documentation,enhancement"

Option 2: Manual Creation

1. Go to https://github.com/liatrio/devops-bootcamp/issues/new
2. Copy the content from this file (starting from "## 🎯 Task Overview")
3. Paste into the issue body
4. Set title: "Task 4.0: Integrated Refactoring Exercise (11.2.5)"
5. Add labels: documentation, enhancement

---

📊 Research Decision Summary

OSS Project Evaluation

Evaluated approach: Research TypeScript/Node.js e-commerce projects on GitHub using search queries targeting MERN/MEAN tutorials, Express API examples, and course repositories with anti-patterns.

Evaluation Criteria:

• Technical Fit (40 pts): TypeScript native, clear anti-patterns, 500-2000 LOC, testable
• Educational Fit (30 pts): Readable code, real-world scenarios, clear refactoring opportunities
• Practical (30 pts): Permissive license, minimal dependencies, maintained

Decision: Build Custom Application

Rationale:

1. Perfect Pedagogical Control: Can tailor anti-patterns to exactly match Repository, Service Layer, and Strategy pattern learning objectives
2. Behavior-Based Testing: Can design test suite that validates behavior, not implementation, ensuring tests pass before and after refactoring
3. No Licensing Concerns: Complete freedom to modify, distribute, and maintain as educational resource
4. Integration with Bootcamp: Matches existing TypeScript conventions from Task 2.0 and Python examples from SOLID exercises
5. Time Investment Justified: 8-12 hour upfront investment creates reusable, customizable educational tool
6. Reproducible and Maintainable: Can create progressive difficulty versions and update as patterns evolve

Alternative Considered: Adapting OSS MERN/MEAN e-commerce tutorials with monolithic structure
Rejected Because: Would require extensive modification (~8 hours) to introduce specific anti-patterns, unclear licensing for educational adaptation, inconsistent with bootcamp quality standards

GitHub Search Strategy Documented: research-notes.md includes comprehensive GitHub search queries and evaluation rubric for future reference if OSS alternative becomes viable