# PlugSnatcher Frontend Refactoring Plan

## Overview

This document outlines a comprehensive plan to refactor the PlugSnatcher frontend from a monolithic structure into a well-organized, modular React application. The refactoring will focus on component separation, state management optimization, and establishing a scalable architecture.

## Current Issues

- All React components are in a single 1300+ line file (`App.tsx`)
- State management is centralized and lacks separation of concerns
- No clear component hierarchy or organization
- Complex UI logic mixed with event handling and API calls
- Poor testability due to tightly coupled components
- Difficulty maintaining and extending the codebase

## Refactoring Goals

- Separate components into individual files with clear responsibilities
- Implement a logical folder structure
- Improve state management using React context or other solutions
- Extract common functionality into hooks and utilities
- Make components more reusable
- Improve code maintainability and readability
- Establish patterns for future development

## Project Structure

```
src/
├── assets/             # Images, icons, and other static files
├── components/         # UI components
│   ├── common/         # Reusable UI components
│   │   ├── Button/
│   │   ├── Modal/
│   │   ├── ProgressBar/
│   │   └── ...
│   ├── layout/         # Layout components
│   │   ├── Header/
│   │   ├── Footer/
│   │   └── ...
│   ├── plugins/        # Plugin-related components
│   │   ├── PluginList/
│   │   ├── PluginItem/
│   │   ├── PluginDetails/
│   │   └── ...
│   ├── server/         # Server-related components
│   │   ├── ServerSelector/
│   │   ├── ServerInfo/
│   │   └── ...
│   └── updates/        # Update-related components
│       ├── UpdateControls/
│       ├── CompatibilityCheck/
│       └── ...
├── context/            # React context providers
│   ├── ServerContext/
│   ├── PluginContext/
│   └── ...
├── hooks/              # Custom React hooks
│   ├── usePluginActions.ts
│   ├── useServerActions.ts
│   ├── useEventListeners.ts
│   └── ...
├── services/           # API and service functions
│   ├── tauriInvoke.ts
│   ├── eventListeners.ts
│   └── ...
├── types/              # TypeScript type definitions
│   ├── plugin.types.ts
│   ├── server.types.ts
│   └── ...
├── utils/              # Utility functions
│   ├── formatters.ts
│   ├── validators.ts
│   └── ...
├── App.tsx             # Main App component (refactored)
└── main.tsx            # Entry point
```

## Implementation Checklist

### Phase 1: Setup Project Structure and Types ✅

- [x] Create folder structure as outlined above
- [x] Extract TypeScript interfaces to separate files
  - [x] Create `types/plugin.types.ts` for Plugin interfaces
  - [x] Create `types/server.types.ts` for Server interfaces
  - [x] Create `types/events.types.ts` for Event payloads

### Phase 2: Extract Utility Functions ✅

- [x] Create utility files
  - [x] `utils/serverUtils.ts` - Server type icons and helpers
  - [x] `utils/formatters.ts` - Text formatting functions
  - [x] `utils/validators.ts` - Data validation functions

### Phase 3: Extract Common UI Components ✅

- [x] Create common UI components
  - [x] `components/common/Modal/Modal.tsx` - Base modal component
  - [x] `components/common/ProgressBar/ProgressBar.tsx` - Progress indicator
  - [x] `components/common/Button/Button.tsx` - Styled button component
  - [x] `components/common/Badge/Badge.tsx` - For platform compatibility badges

### Phase 4: Implement Context for State Management ✅

- [x] Create server context
  - [x] `context/ServerContext/ServerContext.tsx` - Server state provider
  - [x] `context/ServerContext/useServerContext.ts` - Server context hook
- [x] Create plugin context
  - [x] `context/PluginContext/PluginContext.tsx` - Plugin state provider
  - [x] `context/PluginContext/usePluginContext.ts` - Plugin context hook
- [x] Create UI context
  - [x] `context/UIContext/UIContext.tsx` - UI state provider (modals, errors)
  - [x] `context/UIContext/useUIContext.ts` - UI context hook

### Phase 5: Create Custom Hooks ✅

- [x] Create event listener hooks
  - [x] `hooks/useEventListeners.ts` - Tauri event listener setup
- [x] Create server action hooks
  - [x] `hooks/useServerActions.ts` - Server-related actions
- [x] Create plugin action hooks
  - [x] `hooks/usePluginActions.ts` - Plugin-related actions
  - [x] `hooks/useUpdateActions.ts` - Update-related actions

### Phase 6: Implement UI Components

#### Layout Components:
- ✅ Footer - Display application version and GitHub link
- ✅ MainContent - Main application content container
- ✅ ServerSelector - For selecting and managing server paths
- ✅ ServerInfo - Display information about the selected server
- ✅ ScanProgress - Show progress during server scanning

#### Plugin Components:
- ✅ PluginList - Container for listing all plugins
- ✅ PluginItem - Individual plugin display with actions
- ✅ PluginDetails - Detailed view of a plugin
- ✅ NoPluginsMessage - Message shown when no plugins are found

#### Update Components:
- ✅ UpdateControls - Controls for managing plugin updates
- ✅ BulkUpdateProgress - Shows progress during bulk updates
- ✅ CompatibilityCheckDialog - Confirms compatibility before update
- ✅ PremiumPluginModal - Info for premium plugins
- ✅ DownloadProgressIndicator - Shows download progress
- ✅ PluginMatchSelector - For selecting from potential plugin matches
- ✅ WarningModal - For displaying important warnings to users

#### Additional Steps:
- ✅ Fixed linter errors related to Tauri API imports
- ✅ Added TypeScript declarations for Tauri API modules

### Phase 7: Refactor Main App Component ✅

- ✅ Streamline App.tsx to use new components and contexts
- ✅ Remove direct state management from App.tsx
- ✅ Implement provider wrapping in the component tree
- ✅ Verify all functionality works as before

### Phase 8: Performance Optimizations

- [x] Add React.memo() to prevent unnecessary renders
- [ ] Optimize context usage to prevent unnecessary re-renders
- [x] Use callback and memoization for expensive operations
- [ ] Review and optimize state update patterns

### Phase 9: Testing and Documentation

- [ ] Add component documentation
- [ ] Add JSDoc comments for functions and hooks
- [ ] Set up unit testing framework
- [ ] Write tests for critical components

### Phase 10: Final Review and Cleanup

- [ ] Remove unused code and comments
- [ ] Ensure consistent naming conventions
- [ ] Verify all features work correctly
- [ ] Review for any performance issues
- [ ] Finalize documentation

## Implementation Strategy

### Approach

1. **Incremental Migration**: Refactor incrementally, keeping the app functional at each step
2. **Component by Component**: Start with smaller, leaf components and work upward
3. **Test Frequently**: Verify functionality after each significant change
4. **State Migration**: Move state management to context providers gradually

### Best Practices

- Keep components focused on a single responsibility
- Use TypeScript interfaces for all component props
- Maintain clear separation between UI components and business logic
- Follow consistent naming conventions
- Use React's composition pattern for component reuse
- Document complex logic with comments

## Future Enhancements

- Consider adding a state management library if complexity increases (Redux, Zustand, etc.)
- Implement React Router for potential multi-page navigation
- Add i18n for internationalization
- Implement error boundary components for better error handling
- Set up automated testing workflows

## Conclusion

This refactoring plan provides a comprehensive roadmap for transforming the PlugSnatcher frontend into a maintainable, modular React application. By following this plan, we will address the current issues and establish patterns that support future development and scaling of the application.