homepage/REFACTORING_PLAN.md

Refactoring Plan

Generated: 2025-11-18

Overview

This document outlines the step-by-step plan to refactor the homepage codebase, eliminate duplication, and add comprehensive testing.

---

Phase 1: Testing Infrastructure Setup

1.1 Install Testing Dependencies

npm install -D vitest @testing-library/svelte @testing-library/jest-dom @vitest/ui
npm install -D @playwright/test

1.2 Configure Vitest

• Create vitest.config.ts for unit/component tests
• Configure Svelte component testing
• Set up test utilities and helpers

1.3 Configure Playwright

• Create playwright.config.ts for E2E tests
• Set up test fixtures and helpers

1.4 Add Test Scripts

• Update package.json with test commands
• Add coverage reporting

---

Phase 2: Backend Refactoring

2.1 Database Connection Consolidation

Priority: 🔴 Critical

Current State:

• ❌ src/lib/db/db.ts (legacy, uses MONGODB_URI)
• ✅ src/utils/db.ts (preferred, better pooling, uses MONGO_URL)

Action Plan:

1. ✅ Keep src/utils/db.ts as the single source of truth
2. Update all imports to use src/utils/db.ts
3. Delete src/lib/db/db.ts
4. Update environment variable docs

Files to Update (43 total):

• All API route files in src/routes/api/
• src/hooks.server.ts
• Any other imports

2.2 Extract Auth Middleware

Priority: 🔴 Critical

Duplication: Authorization check repeated 47 times across API routes

Current Pattern:

const session = await locals.auth();
if (!session || !session.user?.nickname) {
  return json({ error: 'Unauthorized' }, { status: 401 });
}

Action Plan:

1. Create src/lib/server/middleware/auth.ts
2. Export requireAuth() helper function
3. Update all 47 API routes to use helper
4. Add unit tests for auth middleware

New Pattern:

import { requireAuth } from '$lib/server/middleware/auth';

export async function GET({ locals }) {
  const user = await requireAuth(locals);
  // user is guaranteed to exist here
}

2.3 Create Shared Utilities

Priority: 🟡 Moderate

New Files:

1. src/lib/utils/formatters.ts

   • formatCurrency(amount, currency)
   • formatDate(date, locale)
   • formatNumber(num, decimals)

2. src/lib/utils/errors.ts

   • createErrorResponse(message, status)
   • Standard error types

3. src/lib/server/middleware/validation.ts

   • Request body validation helpers

2.4 Backend Unit Tests

Priority: 🔴 Critical

Test Coverage:

1. Models (10 files)

   • Validation logic
   • Schema defaults
   • Instance methods

2. Utilities (4 files)

   • src/lib/utils/currency.ts
   • src/lib/utils/recurring.ts
   • src/lib/utils/settlements.ts
   • New formatters

3. Middleware

   • Auth helpers
   • Error handlers

Test Structure:

tests/
  unit/
    models/
    utils/
    middleware/

---

Phase 3: Frontend JavaScript Refactoring

3.1 Consolidate Formatters

Priority: 🟡 Moderate

Duplication: 65 formatting function calls across 12 files

Action Plan:

1. Create src/lib/utils/formatters.ts (shared between client/server)
2. Find all inline formatting logic
3. Replace with imported functions
4. Add unit tests

Files with Formatting Logic:

• Cospend pages (8 files)
• Recipe components (4+ files)

3.2 Shared Type Definitions

Priority: 🟢 Minor

Action Plan:

1. Audit src/types/types.ts
2. Add missing types from models
3. Create shared interfaces for API responses
4. Add JSDoc comments

3.3 Frontend Utility Tests

Priority: 🟡 Moderate

Test Coverage:

1. Stores

   • img_store.js
   • portions_store.js
   • season_store.js

2. Utils

   • randomize.js
   • recipeJsonLd.ts
   • stripHtmlTags.ts
   • cookie.js

---

Phase 4: Frontend Design Refactoring

4.1 Create Unified Button Component

Priority: 🟡 Moderate

Duplication: 121 button style definitions across 20 files

Action Plan:

1. Create src/lib/components/ui/Button.svelte
2. Support variants: primary, secondary, danger, ghost
3. Support sizes: sm, md, lg
4. Replace all button instances
5. Add Storybook examples (optional)

New Usage:

<Button variant="primary" size="md" on:click={handleClick}>
  Click me
</Button>

4.2 Extract Modal Component

Priority: 🟡 Moderate

Action Plan:

1. Create src/lib/components/ui/Modal.svelte
2. Extract common modal patterns from PaymentModal.svelte
3. Make generic and reusable
4. Add accessibility (ARIA, focus trap, ESC key)

4.3 Consolidate CSS Variables

Priority: 🟢 Minor

Action Plan:

1. Audit src/lib/css/nordtheme.css
2. Add missing design tokens:
   • --border-radius-sm: 0.25rem
   • --border-radius-md: 0.5rem
   • --border-radius-lg: 1rem
   • Spacing scale
   • Typography scale
3. Replace hardcoded values throughout codebase

4.4 Extract Recipe Filter Component

Priority: 🟢 Minor

Duplication: Similar filtering logic in 5+ pages

Action Plan:

1. Create src/lib/components/recipes/RecipeFilter.svelte
2. Support multiple filter types
3. Replace filtering logic in:
   • Category pages
   • Icon pages
   • Tag pages
   • Season pages
   • Search page

4.5 Decompose Large Components

Priority: 🟢 Minor

Large Files:

• src/routes/cospend/+page.svelte (20KB)
• src/lib/components/PaymentModal.svelte (716 lines)
• src/lib/components/Card.svelte (259 lines)

Action Plan:

1. Break down cospend dashboard into smaller components
2. Extract sections from PaymentModal
3. Simplify Card component

4.6 Component Tests

Priority: 🟡 Moderate

Test Coverage:

1. UI Components

   • Button variants and states
   • Modal open/close behavior
   • Form components

2. Feature Components

   • Recipe card rendering
   • Payment modal calculations
   • Filter interactions

Test Structure:

tests/
  components/
    ui/
    recipes/
    cospend/
    fitness/

---

Phase 5: API Integration Tests

5.1 API Route Tests

Priority: 🔴 Critical

Test Coverage:

1. Cospend API (13 endpoints)

   • Balance calculations
   • Payment CRUD
   • Recurring payment logic
   • Currency conversion

2. Recipe API (17 endpoints)

   • Recipe CRUD
   • Search functionality
   • Favorites
   • Image upload

3. Fitness API (8 endpoints)

   • Exercise CRUD
   • Session tracking
   • Template management

4. Mario Kart API (8 endpoints)

   • Tournament management
   • Bracket generation
   • Score tracking

Test Structure:

tests/
  integration/
    api/
      cospend/
      rezepte/
      fitness/
      mario-kart/

---

Phase 6: E2E Tests

6.1 Critical User Flows

Priority: 🟡 Moderate

Test Scenarios:

1. Recipe Management

   • Create new recipe
   • Edit recipe
   • Add images
   • Mark as favorite
   • Search recipes

2. Expense Tracking

   • Add payment
   • Split payment
   • View balance
   • Calculate settlements

3. Fitness Tracking

   • Create workout template
   • Start workout
   • Log session

Test Structure:

tests/
  e2e/
    recipes/
    cospend/
    fitness/

---

Phase 7: Documentation & Cleanup

7.1 Update Documentation

• Update README with testing instructions
• Document new component API
• Add JSDoc comments to utilities
• Create architecture decision records (ADRs)

7.2 Clean Up Unused Code

• Remove old DB connection file
• Delete unused imports
• Remove commented code
• Clean up console.logs

7.3 Code Quality

• Run ESLint and fix issues
• Run Prettier for formatting
• Check for unused dependencies
• Update package versions

---

Implementation Order

Sprint 1: Foundation (Week 1)

1. ✅ Set up testing infrastructure
2. ✅ Consolidate DB connections
3. ✅ Extract auth middleware
4. ✅ Create formatter utilities
5. ✅ Write backend unit tests

Sprint 2: Backend Cleanup (Week 1-2)

6. ✅ Refactor all API routes
7. ✅ Add API integration tests
8. ✅ Document backend changes

Sprint 3: Frontend JavaScript (Week 2)

9. ✅ Consolidate formatters in frontend
10. ✅ Update type definitions
11. ✅ Add utility tests

Sprint 4: UI Components (Week 3)

12. ✅ Create Button component
13. ✅ Create Modal component
14. ✅ Add CSS variables
15. ✅ Component tests

Sprint 5: Component Refactoring (Week 3-4)

16. ✅ Refactor large components
17. ✅ Extract filter components
18. ✅ Update all usages

Sprint 6: Testing & Polish (Week 4)

19. ✅ E2E critical flows
20. ✅ Documentation
21. ✅ Code cleanup
22. ✅ Final verification

---

Success Metrics

Code Quality

• Zero duplication of DB connections
• <5% code duplication overall
• All components <200 lines
• All utilities have unit tests

Test Coverage

• Backend: >80% coverage
• Frontend utils: >80% coverage
• Components: >60% coverage
• E2E: All critical flows covered

Performance

• No regression in API response times
• No regression in page load times
• Bundle size not increased

Developer Experience

• All tests pass in CI/CD
• Clear documentation
• Easy to add new features
• Consistent code patterns

---

Risk Mitigation

Breaking Changes

• Run full test suite after each refactor
• Keep old code until tests pass
• Deploy incrementally with feature flags

Database Migration

• Ensure MONGO_URL env var is set
• Test connection pooling under load
• Monitor for connection leaks

Component Changes

• Use visual regression testing
• Manual QA of affected pages
• Gradual rollout of new components

---

Rollback Plan

If issues arise:

1. Revert to previous commit
2. Identify failing tests
3. Fix issues in isolation
4. Redeploy with fixes

---

Notes

• All refactoring will be done incrementally
• Tests will be written BEFORE refactoring
• No feature will be broken
• Code will be more maintainable
• Future development will be faster