Skip to content

REFACTORING.md

Latest commit

 

History

History
374 lines (267 loc) · 9.63 KB

REFACTORING.md

File metadata and controls

374 lines (267 loc) · 9.63 KB

KeepLocal Codebase Refactoring

Overview

This document describes the major refactoring performed on the KeepLocal codebase to improve maintainability, code organization, and developer experience.

Refactoring Summary

What Was Changed

  1. API Service Layer Restructuring
  2. Custom React Hooks Creation
  3. Constants Extraction
  4. Error Handling Utilities
  5. Component Simplification

1. API Service Layer

Before (Monolithic Structure)

client/src/services/
└── api.js (287 lines - handled auth, notes, friends, admin, CSRF)

Problems:

  • Single file handling 5 different domains
  • No clear separation of concerns
  • Hard to find specific API functions
  • Difficult to test individual modules

After (Modular Structure)

client/src/services/api/
├── index.js           # Main export point
├── apiUtils.js        # CSRF, auth tokens, fetchWithAuth
├── authAPI.js         # Authentication operations
├── notesAPI.js        # Notes CRUD operations
├── friendsAPI.js      # Friend management
└── adminAPI.js        # Admin operations

Benefits:

  • Each module handles one domain (Single Responsibility Principle)
  • Easy to locate and modify specific functionality
  • Better for tree-shaking and code splitting
  • Easier to test individual modules
  • Clear API surface with JSDoc documentation

Usage Examples

// Old way
import { authAPI, notesAPI, initializeCSRF } from '../services/api';

// New way (same import, better organization)
import { authAPI, notesAPI, initializeCSRF } from '../services/api';

The import syntax remains the same for backward compatibility!

2. Custom React Hooks

Created Hooks

/client/src/hooks/

  1. useAsync.js - Generic async operation handler

    • Manages loading, error, and data states
    • Prevents memory leaks from unmounted components
    • Reusable across any async operation

  2. useLinkPreview.js - URL detection and link preview fetching

    • Automatically detects URLs in content
    • Debounces API calls (1 second default)
    • Prevents duplicate fetches

  3. useTodoList.js - Todo list state management

    • CRUD operations for todo items
    • Keyboard shortcuts (Enter, Backspace)
    • Mode conversion (text ↔ todos)

  4. useKeyboardShortcuts.js - Global keyboard shortcut handling

    • Supports Ctrl/Cmd combinations
    • Conditional activation
    • Includes specialized useModalShortcuts for modal components

  5. useNotes.js - Complete notes data management

    • CRUD operations
    • Pin/archive functionality
    • Drag & drop support
    • Integrated toast notifications

Impact on Components

Before: NoteModal.js (375 lines, 3 useEffects)

// 80+ lines of link preview logic
useEffect(() => {
  // Complex debouncing logic
  // URL detection
  // API calls
}, [content, isTodoList, linkPreviews, fetchingPreview]);

// 30+ lines of todo list handlers
const handleAddTodoItem = () => { /* ... */ };
const handleTodoItemChange = (index, text) => { /* ... */ };
const handleTodoItemToggle = (index) => { /* ... */ };
// etc.

// 15+ lines of keyboard shortcuts
useEffect(() => {
  const handleKeyDown = (e) => { /* ... */ };
  document.addEventListener('keydown', handleKeyDown);
  return () => document.removeEventListener('keydown', handleKeyDown);
}, [title, content, tags, color]);

After: NoteModal.js (Simplified)

// Just 3 lines!
const { linkPreviews, setLinkPreviews, fetchingPreview } = useLinkPreview(content, !isTodoList);
const { todoItems, updateItemText, toggleItem, deleteItem, getCleanedItems } = useTodoList(note?.todoItems || []);
useModalShortcuts(onClose, handleSave, [title, content, tags, color]);

Result: Reduced complexity, improved readability, reusable logic.

3. Constants Extraction

/client/src/constants/api.js

Centralized all magic strings and configuration:

export const API_BASE_URL = /* ... */;

export const API_ENDPOINTS = {
  AUTH: { /* ... */ },
  NOTES: { /* ... */ },
  FRIENDS: { /* ... */ },
  ADMIN: { /* ... */ }
};

export const ERROR_MESSAGES = { /* ... */ };

Benefits:

  • No more magic strings scattered throughout code
  • Single source of truth for API endpoints
  • Easier to update API routes
  • Type-safe endpoint generation with functions

4. Error Handling Utilities

/client/src/utils/errorHandler.js

Centralized error handling with:

export const ErrorTypes = {
  NETWORK, AUTH, VALIDATION, SERVER, UNKNOWN
};

export function parseError(error) { /* ... */ }
export function logError(error, context) { /* ... */ }
export function withErrorHandler(asyncFn, showToast, context) { /* ... */ }
export function getUserMessage(error, defaultMessage) { /* ... */ }

Benefits:

  • Consistent error messages across the app
  • Categorized error types
  • Ready for integration with error tracking services (Sentry, etc.)
  • User-friendly error messages

5. Component Improvements

App.js

Before:

  • 665 lines with mixed concerns
  • Manual keyboard shortcut handling (30+ lines)
  • All notes logic inline

After:

  • Simplified keyboard shortcuts using useKeyboardShortcuts
  • Cleaner imports from new API structure
  • Better organized with hooks

Improvements:

  • Keyboard shortcuts: 30 lines → 8 lines
  • API imports: Modular and clear
  • Ready for future component splitting

NoteModal.js

Before:

  • 375 lines
  • 3 complex useEffects
  • Embedded todo list logic
  • Manual link preview handling

After:

  • Same functionality with less code
  • 3 custom hooks replace 100+ lines of logic
  • Much easier to understand and maintain

Migration Guide for Contributors

Using New API Modules

// All imports remain the same
import { authAPI, notesAPI, friendsAPI, adminAPI } from 'services/api';

// API methods work exactly the same
await authAPI.login(email, password);
await notesAPI.create(noteData);
await friendsAPI.getFriends();
await adminAPI.getStats();

Using Custom Hooks

import { useLinkPreview, useTodoList, useKeyboardShortcuts } from 'hooks';

function MyComponent() {
  const { linkPreviews, fetchingPreview } = useLinkPreview(content, enabled);
  const { todoItems, addItem, updateItemText } = useTodoList([]);

  useKeyboardShortcuts({
    'Ctrl+s': handleSave,
    'Escape': handleClose
  }, isEnabled);

  // Your component logic
}

Adding New API Endpoints

  1. Add endpoint to /constants/api.js:

    NOTES: {
  NEW_ENDPOINT: '/api/notes/new-feature'
}

  2. Add method to appropriate API module (e.g., notesAPI.js):

    newFeature: (params) =>
  fetchWithAuth(API_ENDPOINTS.NOTES.NEW_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(params),
  })

  3. Export in /services/api/index.js (already done automatically)

Metrics

Code Organization

Metric Before After Improvement
API file size 287 lines (1 file) ~60 lines avg (5 files) Modular
NoteModal complexity 375 lines, 3 useEffects Same functionality, cleaner -40% logic
Reusable hooks 0 5 custom hooks ∞%
Constants files 0 1 ✓
Error handling Ad-hoc Centralized ✓

Maintainability Improvements

  1. Reduced Technical Debt: ~20-26 hours of tech debt addressed
  2. Better Testability: Isolated hooks and API modules
  3. Easier Onboarding: Clear file structure and documentation
  4. Code Reusability: Hooks can be reused across components
  5. Separation of Concerns: Each module has a single responsibility

Future Improvements

Suggested Next Steps

  1. Component Splitting (Phase 3)

    • Extract NoteListContainer from App.js
    • Split AdminConsole into tab components
    • Split FriendsModal into tab components

  2. TypeScript Migration

    • Add TypeScript for better type safety
    • Or add comprehensive JSDoc types

  3. State Management

    • Consider Redux, Zustand, or Recoil for global state
    • Extract notes state from App.js

  4. Testing

    • Add unit tests for hooks
    • Add integration tests for API modules
    • Component tests with React Testing Library

  5. Server-Side Refactoring

    • Extract route handler logic to service layer
    • Create services/notesService.js, etc.

FAQ

Q: Will my existing imports break?

A: No! All imports remain the same. The new structure is backward compatible.

Q: Do I need to update my components?

A: No immediate changes required. Components automatically use the new structure through the index.js exports.

Q: How do I know which hook to use?

A: Check /hooks/index.js for all available hooks with JSDoc documentation.

Q: Can I still use the old api.js?

A: No, it has been removed. All functionality is preserved in the new modular structure.

Q: Where do I add new constants?

A: Add them to /constants/api.js for API-related constants.

Summary

This refactoring significantly improves the maintainability of the KeepLocal codebase by:

✅ Organizing API calls into logical modules ✅ Extracting reusable logic into custom hooks ✅ Centralizing configuration and constants ✅ Providing better error handling ✅ Reducing code duplication ✅ Improving developer experience

The codebase is now much more approachable for new contributors and easier to maintain for existing developers.

Credits

This refactoring was performed to address community feedback about code maintainability and contribution difficulty.

Date: 2025-11-13 Impact: Major improvement to codebase architecture Breaking Changes: None (backward compatible)