Modularity Refactoring Execution Plan

Version: 1.0 Date: 2025-12-07 Status: ✅ COMPLETED (2025-12-07) Reference: Modularity Refactoring Guide

Executive Summary

This plan breaks down the modularity refactoring into 16 small PRs across 5 phases. Each PR is designed to be:

  • Small: < 500 lines changed
  • Safe: Includes validation steps
  • Independent: Can be reviewed and merged individually
  • Testable: Includes test updates where needed

Timeline Overview

Phase PRs Parallelization Estimated Effort
1: Foundation 3 All 3 in parallel Low
2: Backend Services 4 Sequential Medium
3: Frontend API 2 Sequential Low
4: Frontend Components 5 All 5 in parallel Medium
5: Polish 2 Sequential Medium

Total PRs: 16 Max Parallel Agents: 5 (Phase 4)

Dependency Graph 

Phase 1 (PARALLEL)
├── PR-01: Backend Lambda Response Utilities ──┐
├── PR-02: Backend Lambda Auth Utilities ──────┼── Phase 2 depends on these
└── PR-03: Frontend Centralized API Client ────┴── Phase 3 depends on this

Phase 2 (SEQUENTIAL)
├── PR-04: LessonService
├── PR-05: CourseService
├── PR-06: EnrollmentService
└── PR-07: ProgressService

Phase 3 (SEQUENTIAL)
├── PR-08: Migrate Core API Clients
└── PR-09: Migrate Remaining API Clients

Phase 4 (PARALLEL) - Requires Phase 3 complete
├── PR-10: Refactor CourseGenerationForm
├── PR-11: Refactor CourseForm
├── PR-12: Refactor LessonForm
├── PR-13: Refactor Admin User Edit Page
└── PR-14: Refactor ProgressTab

Phase 5 (SEQUENTIAL)
├── PR-15: Split Authentication Client
└── PR-16: Final Cleanup & Documentation

Phase 1: Foundation (PARALLEL)

Goal: Create shared utilities that eliminate code duplication. Parallelization: All 3 PRs can run simultaneously (no file conflicts).

PR-01: Backend Lambda Response Utilities

Attribute Value
Complexity Low
Files Created 1
Files Modified 0
Risk Level Low
Prompt File prompts/build/01-backend-response-utilities.md

Scope:

  • Create /backend/shared/utils/lambda-response.ts
  • Implement createResponse, createSuccessResponse, createErrorResponse
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/utils/lambda-response
npm run build

PR-02: Backend Lambda Auth Utilities

Attribute Value
Complexity Low
Files Created 2
Files Modified 0
Risk Level Low
Prompt File prompts/build/02-backend-auth-utilities.md

Scope:

  • Create /backend/shared/utils/lambda-auth.ts
  • Create /backend/shared/utils/lambda-errors.ts
  • Implement getAuthContext, requireAuth, requireRole
  • Add custom error classes
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/utils/lambda-auth
npm run test:unit -- backend/shared/utils/lambda-errors
npm run build

PR-03: Frontend Centralized API Client

Attribute Value
Complexity Low
Files Created 2
Files Modified 0
Risk Level Low
Prompt File prompts/build/03-frontend-api-client.md

Scope:

  • Create /frontend/lib/api/api-client.ts
  • Create /frontend/lib/api/api-types.ts
  • Implement ApiClient class with get, post, put, delete methods
  • Add ApiError class for consistent error handling
  • Add comprehensive tests

Validation:

npm run test -- frontend/lib/api/api-client
npm run build

Phase 2: Backend Services (SEQUENTIAL)

Goal: Create service layer between handlers and repositories. Parallelization: Sequential (each builds on patterns from previous). Prerequisite: Phase 1 PR-01 and PR-02 merged.

PR-04: LessonService

Attribute Value
Complexity Medium
Files Created 2
Files Modified 1
Risk Level Medium
Prompt File prompts/build/04-lesson-service.md

Scope:

  • Create /backend/shared/services/LessonService.ts
  • Migrate business logic from lessons handler
  • Update lessons handler to use service
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/services/LessonService
npm run test:unit -- backend/functions/lessons
npm run build

PR-05: CourseService

Attribute Value
Complexity Medium
Files Created 2
Files Modified 1
Risk Level Medium
Prompt File prompts/build/05-course-service.md

Scope:

  • Create /backend/shared/services/CourseService.ts
  • Migrate business logic from courses handler
  • Update courses handler to use service
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/services/CourseService
npm run test:unit -- backend/functions/courses
npm run build

PR-06: EnrollmentService

Attribute Value
Complexity Medium
Files Created 2
Files Modified 1
Risk Level Medium
Prompt File prompts/build/06-enrollment-service.md

Scope:

  • Create /backend/shared/services/EnrollmentService.ts
  • Migrate business logic from enrollments handler
  • Update enrollments handler to use service
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/services/EnrollmentService
npm run test:unit -- backend/functions/enrollments
npm run build

PR-07: ProgressService

Attribute Value
Complexity Medium
Files Created 2
Files Modified 1
Risk Level Medium
Prompt File prompts/build/07-progress-service.md

Scope:

  • Create /backend/shared/services/ProgressService.ts
  • Migrate business logic from progress handler
  • Update progress handler to use service
  • Add comprehensive tests

Validation:

npm run test:unit -- backend/shared/services/ProgressService
npm run test:unit -- backend/functions/progress
npm run build

Phase 3: Frontend API Migration (SEQUENTIAL)

Goal: Migrate all API clients to use centralized ApiClient. Parallelization: Sequential (to avoid merge conflicts). Prerequisite: Phase 1 PR-03 merged.

PR-08: Migrate Core API Clients

Attribute Value
Complexity Low
Files Created 0
Files Modified 4
Risk Level Low
Prompt File prompts/build/08-migrate-core-api-clients.md

Scope:

  • Migrate courses.ts to use ApiClient
  • Migrate lessons.ts to use ApiClient
  • Migrate enrollment-client.ts to use ApiClient
  • Migrate progress.ts to use ApiClient
  • Remove duplicated apiRequest functions

Validation:

npm run test -- frontend/lib/api
npm run build
# Manual: Test course browsing, enrollment, progress tracking

PR-09: Migrate Remaining API Clients

Attribute Value
Complexity Low
Files Created 0
Files Modified 8
Risk Level Low
Prompt File prompts/build/09-migrate-remaining-api-clients.md

Scope:

  • Migrate analytics.ts
  • Migrate admin-analytics.ts
  • Migrate recommendations.ts
  • Migrate ai-generation.ts
  • Migrate users.ts
  • Migrate categories.ts
  • Migrate badges.ts
  • Migrate user-badges.ts

Validation:

npm run test -- frontend/lib/api
npm run build
# Manual: Test admin features, AI generation, badges

Phase 4: Frontend Components (PARALLEL)

Goal: Refactor large components by extracting hooks and sections. Parallelization: All 5 PRs can run simultaneously (different files). Prerequisite: Phase 3 complete.

PR-10: Refactor CourseGenerationForm

Attribute Value
Complexity High
Files Created 6
Files Modified 1
Risk Level Medium
Prompt File prompts/build/10-refactor-course-generation-form.md

Scope:

  • Create useCourseGenerationForm hook
  • Create BasicInfoSection component
  • Create LearningObjectivesSection component
  • Create AdvancedOptionsSection component
  • Create PdfUploadSection component
  • Refactor CourseGenerationForm.tsx (673 → <200 lines)

Validation:

npm run test -- frontend/hooks/useCourseGenerationForm
npm run test -- frontend/components/admin/ai-generation
npm run build
# Manual: Test AI course generation flow

PR-11: Refactor CourseForm

Attribute Value
Complexity Medium
Files Created 4
Files Modified 1
Risk Level Medium
Prompt File prompts/build/11-refactor-course-form.md

Scope:

  • Create useCourseForm hook
  • Create CourseBasicInfo section component
  • Create CourseMetadata section component
  • Refactor CourseForm.tsx (427 → <250 lines)

Validation:

npm run test -- frontend/hooks/useCourseForm
npm run test -- frontend/components/admin/CourseForm
npm run build
# Manual: Test course create/edit flow

PR-12: Refactor LessonForm

Attribute Value
Complexity Medium
Files Created 3
Files Modified 1
Risk Level Medium
Prompt File prompts/build/12-refactor-lesson-form.md

Scope:

  • Create useLessonForm hook
  • Create LessonContentEditor component
  • Refactor LessonForm.tsx (337 → <200 lines)

Validation:

npm run test -- frontend/hooks/useLessonForm
npm run test -- frontend/components/admin/LessonForm
npm run build
# Manual: Test lesson create/edit flow

PR-13: Refactor Admin User Edit Page

Attribute Value
Complexity Medium
Files Created 4
Files Modified 1
Risk Level Medium
Prompt File prompts/build/13-refactor-user-edit-page.md

Scope:

  • Create useUserEditForm hook
  • Create UserProfileSection component
  • Create UserRoleSection component
  • Refactor edit page (531 → <250 lines)

Validation:

npm run test -- frontend/hooks/useUserEditForm
npm run test -- frontend/app/admin/users
npm run build
# Manual: Test user edit flow

PR-14: Refactor ProgressTab

Attribute Value
Complexity Medium
Files Created 3
Files Modified 1
Risk Level Medium
Prompt File prompts/build/14-refactor-progress-tab.md

Scope:

  • Create useProgressStats hook
  • Create analytics calculation service
  • Refactor ProgressTab.tsx (317 → <200 lines)

Validation:

npm run test -- frontend/hooks/useProgressStats
npm run test -- frontend/components/dashboard/ProgressTab
npm run build
# Manual: Test dashboard progress display

Phase 5: Polish (SEQUENTIAL)

Goal: Complete remaining refactoring and cleanup. Parallelization: Sequential. Prerequisite: All previous phases complete.

PR-15: Split Authentication Client

Attribute Value
Complexity High
Files Created 5
Files Modified 1
Risk Level High
Prompt File prompts/build/15-split-auth-client.md

Scope:

  • Create sign-up.ts module
  • Create sign-in.ts module
  • Create session-management.ts module
  • Create password-management.ts module
  • Create auth-service.ts facade
  • Refactor cognito-client.ts (710 → <150 lines per module)

Validation:

npm run test -- frontend/lib/auth
npm run build
# Manual: Test all auth flows (signup, signin, password reset)

PR-16: Final Cleanup & Documentation

Attribute Value
Complexity Low
Files Created 0
Files Modified Multiple
Risk Level Low
Prompt File prompts/build/16-final-cleanup.md

Scope:

  • Remove unused imports across all modified files
  • Update JSDoc comments
  • Update CLAUDE.md with new patterns
  • Create Architecture Decision Record (ADR)
  • Update component documentation

Validation:

npm run lint
npm run build
npm run test

Rollback Strategy

Per-PR Rollback

Each PR can be reverted independently:

# Revert a specific PR
git revert <merge-commit-sha>

Phase Rollback

If an entire phase needs to be rolled back:

# Find the commit before the phase started
git log --oneline

# Create a revert branch
git checkout -b revert/phase-X <commit-before-phase>

# Cherry-pick any fixes needed
git cherry-pick <fix-commits>

Emergency Rollback

If production is affected:

  1. Immediately: Revert to last known good commit
  2. Investigate: Check logs, identify failing component
  3. Fix Forward: Create hotfix PR with minimal changes
  4. Re-apply: After fix, re-apply refactoring with corrections

Success Metrics

Quantitative

Metric Before Target Measurement
Backend handler avg LOC 330 < 100 wc -l on index.ts files
Frontend component max LOC 673 < 200 wc -l on component files
API client total LOC 2,348 < 800 wc -l on api/*.ts
Code duplication instances 26 0 Manual count
Test coverage Current ≥ Current Jest coverage report

Qualitative

  • All tests pass after each PR
  • No regression in functionality
  • Code follows SOLID principles
  • Clear separation of concerns
  • Improved developer experience

Agent Prompts Location

All agent prompts are located in /prompts/build/:

Prompt File Phase PR
01-refactoring-backend-response-utilities.md 1 PR-01
02-refactoring-backend-auth-utilities.md 1 PR-02
03-refactoring-frontend-api-client.md 1 PR-03
04-refactoring-lesson-service.md 2 PR-04
05-refactoring-course-service.md 2 PR-05
06-refactoring-enrollment-service.md 2 PR-06
07-refactoring-progress-service.md 2 PR-07
08-refactoring-migrate-core-api-clients.md 3 PR-08
09-refactoring-migrate-remaining-api-clients.md 3 PR-09
10-refactor-course-generation-form.md 4 PR-10
11-refactor-course-form.md 4 PR-11
12-refactor-lesson-form.md 4 PR-12
13-refactor-user-edit-page.md 4 PR-13
14-refactor-progress-tab.md 4 PR-14
15-split-auth-client.md 5 PR-15
16-final-cleanup.md 5 PR-16

Execution Commands

Start Phase 1 (Parallel) 

# Run all 3 agents in parallel
/workflow-prompt-run 01,02,03 --parallel

Start Phase 2 (Sequential) 

# Run sequentially
/workflow-prompt-run 04,05,06,07 --sequential

Start Phase 3 (Sequential) 

/workflow-prompt-run 08,09 --sequential

Start Phase 4 (Parallel) 

# Run all 5 agents in parallel (maximum parallelization)
/workflow-prompt-run 10,11,12,13,14 --parallel

Start Phase 5 (Sequential) 

/workflow-prompt-run 15,16 --sequential

Document Version: 1.0 Last Updated: 2025-12-07 Maintained By: Development Team

Back to top

Momentum LMS © 2025. Distributed under the MIT license.