ADR-001: Modularity Refactoring

Status

Accepted

Date

2025-12-07

Context

The codebase had grown with several maintainability issues:

Backend handlers contained 300+ lines mixing auth, validation, and business logic
Frontend API clients duplicated error handling and auth token management
Large React components (400-700 lines) were difficult to test and maintain
The monolithic cognito-client.ts (710 lines) mixed all auth concerns

Decision

We refactored the codebase following these principles:

Backend

Shared utilities for common Lambda patterns (responses, auth, errors)
Service layer between handlers and repositories
Handlers reduced to thin orchestration (~100 lines)

Frontend

Centralized API client with automatic auth and error handling
Custom hooks for form/component state logic
Section components for presentational concerns
Modular auth with single-responsibility modules

Consequences

Positive

Improved testability (services can be tested without Lambda event mocking)
Reduced code duplication (API client, response utilities)
Better separation of concerns (hooks vs components)
Easier onboarding (clear patterns to follow)
Smaller files are easier to review and maintain

Negative

More files to navigate
Learning curve for new patterns
Some indirection in following code flow

Metrics Achieved

Metric	Before	After
Backend handler avg LOC	330	~100
Frontend component max LOC	673	~200
API client total LOC	2,348	~800
Code duplication instances	26	0
Auth module LOC	710	~150/module

Implementation Details

Backend Service Layer

New services were created in backend/shared/services/:

CourseService.ts - Course CRUD operations
LessonService.ts - Lesson management
EnrollmentService.ts - Enrollment operations
ProgressService.ts - Progress tracking
BadgeService.ts - Badge and achievement operations

Backend Shared Utilities

New utilities in backend/shared/utils/:

lambda-response.ts - Standardized API responses
lambda-auth.ts - Authentication helpers
lambda-errors.ts - Custom error classes

Frontend API Client

Centralized HTTP client in frontend/lib/api/:

api-client.ts - Core HTTP methods with auth
api-types.ts - Shared type definitions
Domain-specific modules (courses, lessons, enrollments, etc.)

Frontend Component Refactoring

Large components split into hooks and sections:

CourseGenerationForm (673 → ~150 lines)

useCourseGenerationForm.ts - Form state and validation
BasicInfoSection.tsx - Title, category, duration
AudienceSection.tsx - Target audience, difficulty
LearningObjectivesSection.tsx - Objectives management
ReferenceMaterialsSection.tsx - PDF upload, URLs
GenerationOptionsSection.tsx - Generation toggles

LessonForm (400+ → ~200 lines)

useLessonForm.ts - Form state management
Section components for different form areas

Admin User Edit Page (500+ → ~200 lines)

useUserEditForm.ts - User form state
Section components for profile, preferences, etc.

ProgressTab (400+ → ~150 lines)

useProgressStats.ts - Statistics calculations
ProgressStatsSection.tsx - Stats display
CourseProgressSection.tsx - Course progress cards
ActivityChartSection.tsx - Activity visualization

Auth Module Split

Monolithic cognito-client.ts split into:

cognito-config.ts - Cognito configuration
sign-up.ts - User registration
sign-in.ts - User authentication
session.ts - Session management
password.ts - Password operations
social-login.ts - OAuth providers (Google, Facebook, Apple)
index.ts - Public API exports