PROJECT OVERVIEW:
The application aims to empower users to transform their existing or old computer hardware (like mini-PCs, desktops, laptops, or SBCs) into functional and reliable network routers. This addresses the increasing cost of commercial routers, potential import restrictions, and the desire for more control and customization over home networks. The core value proposition is to provide a user-friendly, step-by-step guided experience that demystifies the process of building a custom router, making it accessible even to users with limited technical expertise. The platform will offer tailored guides, automated configuration scripts, and community support, turning underutilized hardware into a powerful networking solution.
TECH STACK:
- Frontend Framework: React.js
- Styling: Tailwind CSS for utility-first styling and rapid UI development.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side navigation.
- Build Tool: Vite for fast development server and optimized builds.
- Form Handling: React Hook Form for robust form validation and management.
- Icons: Heroicons for a clean and consistent icon set.
- Deployment: Vercel or Netlify for seamless deployment and hosting.
CORE FEATURES:
1. **Hardware Compatibility Checker:**
* User Flow: The user navigates to the 'Check Hardware' section. They can either manually input their hardware specifications (CPU type, RAM, number of Ethernet ports, storage type/size) or, in a future iteration, potentially upload system information. The tool validates this input against a database of known compatible hardware and Linux distributions. It provides a compatibility score and suggests suitable Linux distributions (e.g., Debian, Alpine Linux) and necessary network interface requirements.
* Detailed Description: This feature is crucial for setting user expectations. It will analyze user-provided specs (e.g., 'Intel NUC i5, 8GB RAM, 2x Intel GbE NICs, 120GB SSD') and cross-reference with requirements for running common router software stacks (like OpenWrt, pfSense on Linux, or custom iptables/nftables configurations). It will output a clear 'Compatible', 'Partially Compatible', or 'Not Compatible' status with specific reasons and suggestions for improvement or alternative hardware.
2. **Step-by-Step Guided Setup:**
* User Flow: Based on the compatible hardware identified, the user selects a guided setup path. This section presents a series of clear, concise instructions. Each step includes text explanations, relevant commands to run in the Linux terminal, and potentially embedded video tutorials or animated GIFs demonstrating the action. The steps cover OS installation, network interface configuration, firewall setup (iptables/nftables), DHCP server setup, DNS configuration, and Wi-Fi setup (if applicable).
* Detailed Description: This is the core educational component. It will break down complex tasks into manageable steps. For example, installing Debian will be followed by commands to update the system, install essential packages (`net-tools`, `iproute2`, `iptables`), and configure network interfaces using `ifconfig` or `ip` commands. Firewall rules will be presented with clear explanations of what each rule does (e.g., allowing established connections, blocking unwanted incoming traffic). Users can mark steps as complete, and the system tracks their progress.
3. **Automated Configuration Scripts:**
* User Flow: After completing the manual setup steps or as an alternative for simpler setups, users can access a library of scripts. They select a script based on their desired functionality (e.g., 'Basic Firewall Script', 'DHCP Server Script', 'Guest Network Script'). The script is presented with options for customization (e.g., IP address range for DHCP, specific ports to open). The user copies the generated script and executes it on their router.
* Detailed Description: These scripts will be primarily Bash scripts, designed to be run on the target Linux distribution. The script generator will dynamically create the script based on user inputs. For example, a DHCP script generator would ask for the network interface name (e.g., `eth0`), the subnet (e.g., `192.168.1.0/24`), the DHCP range (e.g., `192.168.1.100-192.168.1.200`), and the gateway/DNS server (e.g., `192.168.1.1`). The output is a ready-to-run script that configures `dnsmasq` or `isc-dhcp-server`.
4. **Community Forum & Support:**
* User Flow: Users can access a dedicated forum space to ask questions, share their successful builds, report issues, and help other users. They can categorize posts by hardware, Linux distribution, or problem type. Moderators and potentially the platform team will provide support.
* Detailed Description: This fosters a community and provides a valuable resource for troubleshooting. Features include user profiles, post creation/editing, commenting, upvoting/downvoting answers, and search functionality. It acts as a knowledge base, capturing common problems and their solutions beyond the automated guides.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) structure. A clean, left-hand sidebar navigation for main sections (Dashboard, Hardware Checker, Guides, Scripts, Community, Settings). Main content area displays the selected section. Minimalist header with app logo and user profile access.
- **Color Palette:** Primary: A calming blue (`#4A90E2`). Secondary: A muted gray for backgrounds and borders (`#F5F5F5`, `#E0E0E0`). Accent: A vibrant green (`#7ED321`) for call-to-actions and success states. Text: Dark gray (`#333333`) for readability, white (`#FFFFFF`) on dark backgrounds.
- **Typography:** A modern sans-serif font like Inter or Poppins for headings and body text. Clear hierarchy using font size and weight. Example: H1 (36px, Semibold), H2 (28px, Semibold), Body (16px, Regular).
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows into a single column. Elements adjust size and spacing for optimal viewing on all devices (smartphones, tablets, desktops).
- **Component Styling:** Tailwind CSS utility classes will be used extensively. Custom components will have minimal custom CSS, focusing on composition and Tailwind's `prose` for content areas.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing and global layout.
- `NavigationSidebar.jsx`: Renders the left sidebar menu. Props: `activeItem` (string).
- `Header.jsx`: Renders the top header bar. Props: `user` (object).
- `HardwareChecker.jsx`: Main component for the hardware checker feature. Manages input fields and displays results.
- `HardwareInputForm.jsx`: Form component for user hardware details. Props: `onSubmit`, `initialData`.
- `CompatibilityResult.jsx`: Displays the compatibility check results. Props: `result` (object).
- `GuidedSetup.jsx`: Orchestrates the step-by-step guide process.
- `GuideStep.jsx`: Displays a single step in the guide. Props: `step` (object), `isComplete` (boolean), `onCompleteToggle`.
- `ProgressTracker.jsx`: Visual indicator of guide progress. Props: `currentStep`, `totalSteps`.
- `ScriptGenerator.jsx`: Interface for selecting and configuring scripts.
- `ScriptSelector.jsx`: Lists available scripts. Props: `scripts` (array), `onSelect`.
- `ConfiguratorForm.jsx`: Dynamically generated form for script parameters. Props: `configSchema` (object), `onSubmit`.
- `GeneratedScriptDisplay.jsx`: Shows the generated script. Props: `scriptContent` (string).
- `CommunityForum.jsx`: Displays forum threads and posts.
- `ThreadList.jsx`: Lists forum threads. Props: `threads` (array).
- `PostList.jsx`: Displays posts within a thread. Props: `posts` (array).
- `CreatePostForm.jsx`: Form for creating new posts. Props: `onSubmit`.
- `Modal.jsx`: Generic modal component. Props: `isOpen`, `onClose`, `children`.
- `Button.jsx`: Custom styled button. Props: `variant`, `onClick`, `children`.
- `Input.jsx`: Custom styled input field. Props: `label`, `type`, `value`, `onChange`.
DATA MODEL:
- **State Structure (Zustand Store):**
```javascript
{
hardware: { specs: {}, compatibility: null, suggestions: [] },
guides: { all: [], currentGuide: null, currentStepIndex: 0 },
scripts: { available: [], generatedScript: '' },
community: { threads: [], posts: [], loading: false, error: null },
user: { profile: null, settings: {} },
ui: { modalOpen: false, loadingStates: {} } // e.g., { 'hardwareCheck': true }
}
```
- **Mock Data Formats:**
* `hardwareSpecExample`: `{ cpu: 'Intel Core i5-8250U', ram: '8GB DDR4', storage: '120GB SATA SSD', networkInterfaces: [{ type: 'Ethernet', speed: '1Gbps', count: 2 }], wifi: false }`
* `compatibilityResultExample`: `{ status: 'Compatible', score: 8.5, reasons: ['Sufficient RAM', 'Dual Ethernet ports detected'], recommendedOs: ['Debian 11', 'Alpine Linux'], warnings: ['Consider adding a USB 3.0 Gigabit adapter for WAN if only one onboard NIC is available'] }`
* `guideStepExample`: `{ id: 'os_install', title: 'Install Operating System', description: 'Download the chosen OS image and create a bootable USB drive. Follow the standard installation procedure for your Linux distribution.', commands: ['wget [OS_URL]', 'dd if=~/os.iso of=/dev/sdX bs=4M status=progress'], videoUrl: 'https://example.com/install.mp4', completed: false }`
* `scriptExample`: `{ id: 'basic_firewall', name: 'Basic Firewall Setup', description: 'Sets up essential firewall rules to protect your network.', configSchema: [{ name: 'lanInterface', type: 'text', label: 'LAN Interface Name', defaultValue: 'eth0' }, { name: 'wanInterface', type: 'text', label: 'WAN Interface Name', defaultValue: 'eth1' }], generateScript: (config) => `echo 'Configuring firewall...' # ... iptables rules ...` }`
* `communityThreadExample`: `{ id: 't1', title: 'Success! Mini PC as Router', author: 'TechGuru88', timestamp: '2023-10-27T10:00:00Z', replies: 5 }`
ANIMATIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on buttons and navigation items on hover.
- **Transitions:** Smooth transitions for sidebar collapse/expand, modal opening/closing, and content fading in/out when navigating between sections. Use Tailwind's transition utilities and CSS transitions.
- **Loading States:** Implement skeleton loaders or spinners (using libraries like `react-spinners` or custom SVG animations) for data fetching (e.g., community threads, script generation). Disable buttons and show loading indicators during async operations.
- **Micro-interactions:** Visual feedback when marking a guide step as complete (e.g., a checkmark animation). Success messages that briefly appear and fade for form submissions or script generation.
EDGE CASES:
- **Empty States:** Display user-friendly messages and potentially illustrations for empty lists (e.g., 'No guides available yet', 'Start a new discussion in the community').
- **Error Handling:** Gracefully handle API errors or script generation failures. Display informative error messages to the user (e.g., 'Failed to fetch community threads. Please try again later.'). Use try-catch blocks and display error states clearly.
- **Validation:** Implement real-time form validation for hardware checker inputs and script configuration parameters. Provide clear inline error messages next to invalid fields.
- **Accessibility (a11y):** Ensure all interactive elements are keyboard-navigable. Use semantic HTML (headings, lists, buttons). Provide sufficient color contrast. Use ARIA attributes where necessary (e.g., `aria-label` for icon buttons). Ensure images have `alt` text.
SAMPLE DATA:
1. `Hardware Spec (Mini PC)`: `{ cpu: 'Intel Celeron N5105', ram: '4GB DDR4', storage: '64GB eMMC', networkInterfaces: [{ type: 'Ethernet', speed: '1Gbps', count: 2 }], wifi: false }`
2. `Compatibility Result (Good Fit)`: `{ status: 'Compatible', score: 9.1, reasons: ['Modern low-power CPU', 'Sufficient RAM for basic routing', 'Dual Gigabit Ethernet ports'], recommendedOs: ['OpenWrt (recommended)', 'Debian'], warnings: [] }`
3. `Guide Step (Install Debian)`: `{ id: 'install_debian', title: 'Install Debian Linux', description: 'Boot from your prepared USB drive and follow the Debian installer prompts. Select "Standard system utilities" and "SSH server" during package selection. For network configuration, set up your primary interface (e.g., eth0) with a static IP if needed, or use DHCP.', commands: ['Refer to official Debian installation guide'], videoUrl: 'https://www.youtube.com/watch?v=example_debian_install', completed: false }`
4. `Script Example (DHCP Server)`: `{ id: 'dhcp_server_dnsmasq', name: 'DHCP Server (dnsmasq)', description: 'Configures dnsmasq to provide DHCP and DNS services.', configSchema: [{ name: 'interface', type: 'text', label: 'Interface', defaultValue: 'eth0' }, { name: 'dhcpRangeStart', type: 'text', label: 'DHCP Start IP', defaultValue: '192.168.1.100' }, { name: 'dhcpRangeEnd', type: 'text', label: 'DHCP End IP', defaultValue: '192.168.1.200' }, { name: 'subnetMask', type: 'text', label: 'Subnet Mask', defaultValue: '255.255.255.0' }], generateScript: (cfg) => `sudo apt update && sudo apt install -y dnsmasq
sudo sed -i 's/#dhcp-range=/dhcp-range=${cfg.interface},${cfg.dhcpRangeStart},${cfg.dhcpRangeEnd},${cfg.subnetMask}/' /etc/dnsmasq.conf
sudo systemctl restart dnsmasq` }`
5. `Community Thread (Troubleshooting)`: `{ id: 't2', title: 'WAN connection dropping on Linksys WRT54GL build', author: 'NewbieNet', timestamp: '2023-10-26T18:30:00Z', replies: 12 }`
6. `Hardware Spec (Old Laptop)`: `{ cpu: 'Intel Core 2 Duo T7500', ram: '4GB DDR2', storage: '250GB HDD', networkInterfaces: [{ type: 'Ethernet', speed: '1Gbps', count: 1 }, { type: 'WiFi', speed: '54Mbps', count: 1 }], wifi: true }`
7. `Compatibility Result (Needs Upgrade)`: `{ status: 'Partially Compatible', score: 4.5, reasons: ['Single Ethernet port (ideal is 2+)', 'Slow storage (HDD)'], recommendedOs: ['Alpine Linux (performance focused)'], warnings: ['Requires a USB-to-Ethernet adapter for separate WAN/LAN. Performance may be limited.'] }`
8. `Guide Step (Basic Firewall)`: `{ id: 'basic_firewall', title: 'Configure Basic Firewall Rules', description: 'Apply essential iptables rules to allow established connections and block unwanted incoming traffic. This is a minimal setup.', commands: ['sudo iptables -A INPUT -i lo -j ACCEPT', 'sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT', 'sudo iptables -P INPUT DROP'], videoUrl: null, completed: false }`
9. `Script Example (Web Server - Basic)`: `{ id: 'basic_web_server', name: 'Simple Web Server (nginx)', description: 'Installs and configures nginx to serve a basic HTML page.', configSchema: [{ name: 'port', type: 'number', label: 'Port', defaultValue: 80 }], generateScript: (cfg) => `sudo apt update && sudo apt install -y nginx
sudo systemctl enable nginx
sudo sed -i 's/listen 80 default_server;/listen ${cfg.port} default_server;/' /etc/nginx/sites-available/default
sudo systemctl restart nginx` }`
10. `Community Post Example`: `{ id: 'p1', threadId: 't2', author: 'RouterPro', timestamp: '2023-10-27T09:15:00Z', content: 'Check your kernel logs (`dmesg`) for any USB or NIC errors when the connection drops. It might be a driver issue or power management problem.' }`
DEPLOYMENT NOTES:
- **Build Configuration:** Use Vite's `build` command. Ensure `base` path is correctly configured if deploying to a subdirectory (`vite build --base /app/`).
- **Environment Variables:** Use `.env` files (e.g., `.env.local`, `.env.production`). Key variables might include `VITE_API_URL` (if connecting to a backend API for advanced features), `VITE_COMMUNITY_API_ENDPOINT`.
- **Performance Optimizations:** Code splitting via Vite's automatic chunking. Lazy loading components (e.g., `React.lazy` and `Suspense`) for less critical sections like the Community Forum. Optimize images and assets. Use `React.memo` and `useCallback` to prevent unnecessary re-renders.
- **Routing:** Configure server for SPA fallback (e.g., Vercel's `vercel.json` or Netlify's `_redirects`) to redirect all non-file requests to `index.html`.