173 lines
5.9 KiB
Plaintext
173 lines
5.9 KiB
Plaintext
---
|
|
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**: ALWAYS Check the [ROADMAP.md](mdc: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. |