---
description: 
globs: 
alwaysApply: true
---
# PlugSnatcher Development Workflow

This document outlines the development workflow and best practices for the PlugSnatcher application. Following these guidelines will help maintain consistency and scalability as the project grows.

## Project Architecture

PlugSnatcher is a desktop application built with:
- **Frontend**: React + TypeScript
- **Backend**: Rust + Tauri
- **Data Handling**: In-memory state, potential future SQLite/JSON storage

### Project Structure

```
PlugSnatcher/
├── src/                  # Frontend code (React + TypeScript)
│   ├── App.tsx           # Main application component
│   ├── App.css           # Application styles
│   └── assets/           # Static assets
├── src-tauri/            # Backend code (Rust)
│   ├── src/              # Rust source code
│   │   ├── lib.rs        # Core backend functionality
│   │   └── main.rs       # Tauri application entry point
│   ├── Cargo.toml        # Rust dependencies
│   ├── tauri.conf.json   # Tauri configuration
│   └── capabilities/     # Tauri v2 capabilities configs
├── public/               # Public static files
└── ROADMAP.md            # Project roadmap and progress tracking
```

## Development Workflow

### 1. Feature Planning

1. **Consult Roadmap**: Check the `ROADMAP.md` file to identify the next feature to implement
2. **Define Scope**: Clearly define what the feature will do and identify any dependencies
3. **Update Roadmap**: Mark features as "In Progress" when starting work

### 2. Implementation Process

For each new feature, follow this general workflow:

#### Backend (Rust) Development
1. **Define Data Models**: Create necessary structs and enums in `lib.rs`
2. **Implement Core Logic**: Develop the backend functionality in Rust
3. **Create Tauri Commands**: Expose functionality to the frontend through command annotations
4. **Update Dependencies**: Add any new dependencies to `Cargo.toml`
5. **Configure Permissions**: Update capability files if new permissions are needed

#### Frontend (React) Development
1. **Define Interfaces**: Create TypeScript interfaces that match Rust structs
2. **Implement UI Components**: Create or update React components
3. **Connect to Backend**: Use Tauri's invoke to call Rust functions
4. **Style Components**: Update CSS for new UI elements
5. **Handle Edge Cases**: Ensure proper error handling and loading states

### 3. Testing

- **Manual Testing**: Test features thoroughly on Windows (primary platform)
- **Edge Cases**: Test with various plugin formats and server setups
- **Error Handling**: Verify all error paths work correctly

### 4. Documentation

- **Update Roadmap**: Mark completed features
- **Code Documentation**: Add comments for complex logic
- **User Documentation**: Update usage instructions if needed

## Code Conventions

### Rust Conventions

1. **Error Handling**:
   - Use `Result<T, String>` for functions that may fail
   - Provide descriptive error messages
   - Use the `?` operator with `.map_err()` for context

2. **Struct Definitions**:
   - Include `#[derive]` attributes for serialization
   - Organize fields logically
   - Use proper visibility modifiers (pub when needed)

3. **Function Organization**:
   - Group related functions together
   - Extract helper functions for reusable logic
   - Add documentation comments for public functions

### TypeScript/React Conventions

1. **Component Structure**:
   - Use functional components with hooks
   - Define props interfaces for all components
   - Keep components focused on a single responsibility

2. **State Management**:
   - Use React's `useState` for local state
   - Use `useContext` if state needs to be shared
   - Consider state management libraries for complex state (future enhancement)

3. **Styling Approach**:
   - Use CSS variables for theming
   - Organize CSS by component hierarchy
   - Use consistent naming conventions

## Scalability Considerations

### Performance Optimization

1. **Large Plugin Collections**:
   - Implement pagination or virtualization for long lists
   - Optimize file scanning operations
   - Consider background processing for intensive operations

2. **Memory Management**:
   - Be mindful of memory usage with large JAR files
   - Release resources properly after use

### Future Extensions

1. **Plugin Architecture**:
   - Design the crawler system with flexibility for multiple sources
   - Use interfaces and traits for different plugin repository types

2. **Database Integration**:
   - Prepare for potential migration to a database for persistent storage
   - Design data models with this in mind

3. **Multi-Server Management**:
   - Consider how the architecture might expand to handle multiple servers

## Troubleshooting Common Issues

### Rust/Tauri Issues

1. **Permission Errors**:
   - Check Tauri capability files in `capabilities/` directory
   - Ensure proper permissions are granted for each plugin

2. **Build Errors**:
   - Verify Rust dependencies in `Cargo.toml`
   - Check for incompatible versions

### TypeScript/React Issues

1. **Type Errors**:
   - Ensure TypeScript interfaces match Rust structs
   - Use proper type assertions for nullable values

2. **UI Rendering Issues**:
   - Check CSS specificity and hierarchy
   - Verify conditional rendering logic

## Deployment Process

1. **Version Bump**:
   - Update version in `package.json` and `Cargo.toml`

2. **Build Process**:
   - Run `npm run tauri build` for production builds
   - Test the packaged application before distribution

3. **Distribution**:
   - Package for Windows (primary platform)
   - Consider multi-platform support as needed

## Conclusion

By following this workflow, the PlugSnatcher project will maintain a consistent structure and approach as it scales. This document should be updated as the project evolves to reflect any changes in best practices or architecture.