Build A Modern React Backup UI Frontend
# Building a Modern React-Based Web Frontend for Backup Management
**Modernizing Backup Management with React:** The evolution of data management necessitates user-friendly interfaces, and this project aims to create a cutting-edge, React-based web frontend. This interface will replace the current API-only access pattern, making backup management accessible to both technical and non-technical users. This project aims to simplify data management, visualize backup processes, and streamline configuration and troubleshooting, ultimately improving the user experience.
### Motivation: Why a Web UI?
Currently, managing backups involves API calls and CLI scripts, which can be daunting for non-technical users. A web UI offers several advantages. Firstly, it **empowers non-technical users** to manage their backups independently, fostering greater control. Secondly, it provides **visual feedback on backup status and verification**, making it easier to understand the progress and outcomes of backup jobs. Thirdly, it **streamlines configuration and troubleshooting** through an intuitive interface, reducing the complexity associated with the CLI and API calls. Finally, the web UI will **display real-time job progress and notifications**, ensuring that users are always informed about the status of their backups, enhancing transparency and user engagement.
### Technology Stack
The project leverages a modern technology stack to ensure a robust and efficient frontend. This includes:
* ***Framework***: React 18+ with TypeScript - This pairing provides a strong foundation for building dynamic and scalable user interfaces. React's component-based architecture enhances code reusability and maintainability, while TypeScript adds static typing, improving code quality.
* ***UI Library***: Material-UI (MUI) - MUI offers pre-built, customizable UI components that adhere to Google's Material Design principles. It accelerates development by providing a consistent and visually appealing user interface.
* ***State Management***: React Query + Context API - React Query simplifies data fetching, caching, and state management, providing a smooth and responsive user experience. The Context API manages global state, allowing data to be shared across components without prop drilling.
* ***Real-time Updates***: WebSocket for job progress - WebSockets enable real-time communication between the frontend and the backend. This is crucial for displaying live job progress updates, providing users with immediate feedback on their backup operations.
* ***Build Tool***: Vite or Create React App - Vite and Create React App are modern build tools that streamline the development process. They handle tasks like bundling, transpilation, and hot module replacement, increasing developer productivity.
* ***API Client***: Axios with OpenAPI code generation - Axios is a popular HTTP client used for making API requests. OpenAPI code generation streamlines the integration with the backend API by automatically generating TypeScript types and client code based on the OpenAPI specification.
## Core Features
The web frontend is designed to offer a comprehensive set of features, including:
### 1. Authentication & Authorization
* A secure login page using JWT token support for authentication.
* Session management with refresh tokens for continuous user sessions.
* Role-based UI elements, tailored for ADMIN, OPERATOR, and VIEWER roles.
* Logout functionality for secure session termination.
* A password change interface to allow users to update their credentials.
### 2. Dashboard
* An overview of the backup status, including completed, failed, and running jobs.
* A recent backup activity timeline, displaying the most recent backup events.
* Storage backend utilization charts, providing visual insights into storage usage.
* An alerts and notifications panel, alerting users to important events.
* Quick actions, such as the ability to trigger a backup or verify the latest backup.
### 3. Backup Management
* A list of all backups with filtering capabilities based on source, date, and status.
* A backup details page providing comprehensive verification status information.
* A ***"Test Restore" button*** enabling users to trigger verification (addressing Issue #6).
* An interface for manual backup triggering.
* Backup deletion functionality, with a confirmation prompt for safety.
* Download options for backup metadata and logs.
* Visual indicators for verified and unverified backups, improving clarity.
### 4. VM & Container Management
* Listing VMs from KVM hosts.
* Listing containers from Podman hosts.
* One-click backup trigger per VM/container.
* Viewing backup history per source.
* Configuring backup schedules per source.
### 5. Backup Schedules
* A comprehensive list of all backup schedules.
* The ability to create new schedules using a cron expression builder.
* Schedule editing capabilities.
* Enabling/disabling schedules based on user preferences.
* Configuring retention policies for each schedule.
* A visual schedule calendar view for intuitive scheduling.
### 6. Storage Backends
* A list of all configured storage backends.
* The ability to add new storage backends (Local, SMB, NFS, S3).
* Testing storage backend connections to verify functionality.
* Editing storage configurations.
* Viewing storage usage statistics.
* Deleting storage backends, with appropriate warnings.
### 7. Infrastructure Management
* Listing KVM hosts with their connection status.
* Adding and editing KVM hosts.
* SSH key upload and management (addressing Issue #4).
* Password authentication configuration.
* Testing host connectivity.
* Listing Podman hosts, with features similar to KVM hosts.
### 8. Jobs & Task Monitoring
* A real-time job status dashboard.
* A job logs viewer with filtering capabilities.
* The ability to cancel running jobs.
* Retrying failed jobs.
* Job history with search functionality.
* WebSocket updates for live job progress.
### 9. Verification Management
* A verification status dashboard.
* Triggering verification from backup details.
* Viewing verification history.
* Configuring an automated verification schedule.
* Email notification settings for verification outcomes.
### 10. User Management (Admin Only)
* Listing all users.
* Creating new user accounts.
* Editing user roles.
* Disabling/enabling user accounts.
* Password reset functionalities.
### 11. System Settings
* Configuring SMTP settings for email notifications.
* Setting default retention policies.
* Configuring encryption settings.
* System health checks to ensure proper operation.
* Viewing system logs for troubleshooting.
* Database backup schedule configuration.
### 12. Encryption Key Management (Addressing Issue #7)
* Viewing encryption key status.
* Exporting encryption keys (with appropriate warnings).
* Importing encryption keys during recovery.
* A key rotation interface for enhanced security.
* Per-storage encryption key configuration.
## UI/UX Requirements
The UI/UX design will follow these principles:
### Design Principles
* ***Clarity***: Clear status indicators using color-coding (green/yellow/red).
* ***Accessibility***: Compliance with WCAG 2.1 Level AA standards, ensuring usability for everyone.
* ***Responsiveness***: Mobile-friendly design, with a minimum tablet size.
* ***Performance***: Fast initial loading times and lazy loading for long lists, optimizing performance.
* ***Feedback***: Visual feedback, including loading states and success/error notifications, to keep users informed.
### Key UI Elements
* ***Navigation***: Sidebar navigation with icons for easy access to features.
* ***Notifications***: Toast notifications for user actions.
* ***Confirmations***: Modal dialogs for destructive actions, providing an extra layer of safety.
* ***Real-time***: Live updates to track job progress.
* ***Data Tables***: Sortable, filterable, and paginated lists to handle large datasets effectively.
* ***Forms***: Input validation with clear error messages for a better user experience.
## API Integration
The frontend will integrate seamlessly with existing FastAPI endpoints:
* Leveraging fully documented API endpoints.
* Using the OpenAPI spec at `/docs` to generate a TypeScript client, improving code generation and type safety.
* Handling authentication with JWT Bearer tokens.
* Utilizing WebSocket connections for real-time updates on job progress.
* Implementing robust error handling with user-friendly messages.
## Example Page Layouts
### Dashboard
The dashboard will provide a comprehensive overview of system status and recent activity, shown below.
┌─────────────────────────────────────────────────┐ │ Lab Backup System [User ▾] [Logout]│ ├─────────────────────────────────────────────────┤ │ ■ Dashboard ┌─────────────────────────────┐ │ │ □ Backups │ System Status │ │ │ □ Schedules │ ✓ 47 completed (24h) │ │ │ □ VMs │ ✗ 2 failed (24h) │ │ │ □ Containers │ ○ 3 running now │ │ │ □ Storage │ │ │ │ □ Jobs ├─────────────────────────────┤ │ │ □ Settings │ Storage Usage │ │ │ □ Users │ [████████░░] 80% (500 GB) │ │ │ ├─────────────────────────────┤ │ │ │ Recent Activity │ │ │ │ ✓ vm-web backup completed │ │ │ │ ✓ vm-db verified (passed) │ │ │ │ ○ vm-app backup running... │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────────────────┘
### Backup Details with Verification
The backup details page will provide detailed information about individual backups, including verification status.
┌─────────────────────────────────────────────────┐ │ Backup Details: vm-webserver-20251117 │ ├─────────────────────────────────────────────────┤ │ Status: ✓ Completed │ │ Source: vm-webserver (VM) │ │ Type: Full Backup (Daily) │ │ Size: 5.0 GB (compressed: 2.0 GB) │ │ Created: 2025-11-17 12:00 UTC │ │ Expires: 2025-12-17 12:00 UTC │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Verification Status: ✓ PASSED │ │ │ │ Last Verified: 2025-11-17 14:30 UTC │ │ │ │ Tables: 47 | Size: 2.3 GB | Duration: 45s│ │ │ │ │ │ │ │ [Test Restore] [Download] [Restore] [Delete]│ │ │ └─────────────────────────────────────────────┘ │ │ │ │ Storage: s3-backblaze │ │ Path: vms/vm-webserver/... │ │ Encryption: ✓ Enabled │ └─────────────────────────────────────────────────┘
## Implementation Phases
The project will be implemented in phases:
### Phase 1: Foundation (Week 1)
* Project setup with React + TypeScript + MUI.
* Authentication system implementation (login/logout).
* Creating an API client with TypeScript types.
* Establishing a basic layout with navigation.
* Developing a skeleton of the dashboard.
### Phase 2: Core Features (Week 2)
* Developing backup listing and detailed views.
* Implementing the verification UI with the ***"Test Restore" button***.
* Listing VMs and containers.
* Managing storage backends.
* Implementing job monitoring functionality.
### Phase 3: Advanced Features (Week 3)
* Developing the backup schedules UI.
* Implementing user management functionality.
* Developing the system settings interface.
* Implementing real-time WebSocket updates for live information.
* Managing encryption keys.
### Phase 4: Polish (Week 4)
* Refining the responsive design for different devices.
* Improving accessibility features.
* Implementing robust error handling and input validation.
* Optimizing performance.
* Conducting user testing and fixing bugs.
## Acceptance Criteria
This project will meet the acceptance criteria below:
* The user can successfully log in and access the dashboard.
* The user can view all backups and their verification status.
* The user can initiate the verification process using the "Test Restore" button.
* The user can create backup schedules with cron expressions.
* The user can trigger one-time backups.
* The user can configure storage backends.
* The user can monitor running jobs in real-time.
* The admin can effectively manage users and system settings.
* All forms incorporate proper input validation.
* Destructive actions require confirmation.
* The application is fully responsive on tablets and desktops.
* No console errors or warnings are present.
* API errors are displayed with user-friendly messages.
## Technical Considerations
### Security
* **XSS protection**: Sanitizing all user inputs to mitigate cross-site scripting attacks.
* **CSRF tokens**: Implementing CSRF tokens for state-changing operations to protect against cross-site request forgery.
* **Secure token storage**: Using `httpOnly` cookies or secure local storage for secure token storage.
* **Role-based component rendering**: Ensuring that UI components are rendered based on user roles.
* **Audit logging**: Implementing audit logging for admin actions to track activity.
### Performance
* **Code splitting**: Implementing code splitting for faster initial loading times.
* **Virtual scrolling**: Employing virtual scrolling for managing large backup lists efficiently.
* **Debounced search inputs**: Using debouncing for search inputs to reduce unnecessary API calls.
* **Optimistic UI updates**: Implementing optimistic UI updates to enhance perceived performance.
* **Caching with React Query**: Utilizing caching with React Query to minimize data fetching and improve responsiveness.
### Testing
* **Unit tests**: Writing unit tests for critical components to ensure functionality.
* **Integration tests**: Conducting integration tests for key workflows to verify interactions between components.
* **E2E tests**: Implementing E2E tests for authentication and backup verification to simulate user interactions.
* **Accessibility testing**: Performing accessibility testing with axe-core to ensure compliance with accessibility standards.
## Dependencies
The project relies on:
**Requires**: Completion of Issue #7 (encryption key management API), and existing API endpoints.
**Blocks**: No blocking dependencies, as it is a standalone frontend enhancement.
## Resources
* [Material-UI Documentation](https://mui.com/)
* [React Query Documentation](https://tanstack.com/query/latest)
* [FastAPI OpenAPI](http://localhost:8000/docs)
* [API Verification Docs](docs/API_BACKUP_VERIFICATION.md)
## Success Metrics
The success of this project will be measured by:
* Making 100% of backup operations accessible via the new GUI.
* Achieving an initial page load time of under 2 seconds.
* Having zero critical accessibility violations.
* Enabling users to complete a full backup workflow in under 5 clicks.
* Ensuring that verification triggered from the GUI receives an email report.
For more information on React, explore the official React documentation: React Documentation
