# Network Scanner Frontend - Development Guide ## Architecture ### Component Structure ``` App (Router) └── Layout (Navigation) ├── Dashboard │ ├── ScanForm │ └── Statistics ├── NetworkPage │ ├── NetworkMap (ReactFlow) │ │ └── HostNode (Custom) │ └── HostDetails (Modal) ├── HostsPage │ ├── HostTable │ └── HostDetails (Modal) └── ScansPage └── ScansList ``` ### State Management - **Local State**: React hooks (useState, useEffect) - **Custom Hooks**: Data fetching and WebSocket management - **No Global State**: Each page manages its own data ### Data Flow 1. **REST API** → Custom hooks → Components → UI 2. **WebSocket** → Custom hooks → State updates → UI refresh ## Custom Hooks ### useScans Manages scan data: - Fetches list of scans - Polls for updates - Provides refetch function ```typescript const { scans, loading, error, refetch } = useScans(); ``` ### useHosts Manages host data: - Fetches list of hosts - Gets individual host details - Provides refetch function ```typescript const { hosts, loading, error, refetch } = useHosts(); const { host, loading, error } = useHost(hostId); ``` ### useTopology Manages network topology: - Fetches topology graph data - Provides refetch function ```typescript const { topology, loading, error, refetch } = useTopology(); ``` ### useWebSocket Manages WebSocket connection: - Auto-reconnect on disconnect - Message handling - Connection status ```typescript const { isConnected, reconnect } = useWebSocket({ onScanProgress: (data) => { ... }, onScanComplete: (data) => { ... }, onHostDiscovered: (data) => { ... }, }); ``` ## API Integration ### REST Endpoints All endpoints are proxied through Vite dev server: ```typescript // Development: http://localhost:3000/api/* → http://localhost:8000/api/* // Production: Configure your web server proxy scanApi.startScan(request) scanApi.getScanStatus(id) scanApi.listScans() scanApi.cancelScan(id) hostApi.listHosts(params) hostApi.getHost(id) hostApi.getHostByIp(ip) hostApi.getHostServices(id) hostApi.getHostStatistics() hostApi.deleteHost(id) topologyApi.getTopology() topologyApi.getNeighbors(id) ``` ### WebSocket Messages ```typescript type WSMessage = { type: 'scan_progress' | 'scan_complete' | 'host_discovered' | 'error'; data: any; }; ``` ## Styling ### TailwindCSS Custom theme configuration in `tailwind.config.js`: ```javascript colors: { primary: { ... }, // Blue shades slate: { ... }, // Dark theme } ``` ### Color Scheme - Background: `slate-900` - Cards: `slate-800` - Borders: `slate-700` - Text primary: `slate-100` - Text secondary: `slate-400` - Accent: `primary-500` (blue) ### Responsive Design Mobile-first approach with breakpoints: - `sm`: 640px - `md`: 768px - `lg`: 1024px - `xl`: 1280px ## Network Map (React Flow) ### Custom Node Component `HostNode.tsx` renders each host as a custom node: ```typescript void, }} /> ``` ### Layout Algorithm Currently using circular layout. Can be replaced with: - Force-directed (d3-force) - Hierarchical (dagre) - Manual positioning ### Node Types - **Gateway**: Blue, Globe icon - **Server**: Green, Server icon - **Workstation**: Purple, Monitor icon - **Device**: Amber, Smartphone icon - **Unknown**: Gray, HelpCircle icon ## Adding New Features ### New API Endpoint 1. Add type to `src/types/api.ts` 2. Add service method to `src/services/api.ts` 3. Create custom hook in `src/hooks/` 4. Use in component ### New Page 1. Create component in `src/pages/` 2. Add route to `App.tsx` 3. Add navigation item to `Layout.tsx` ### New Component 1. Create in `src/components/` 2. Follow existing patterns 3. Use TypeScript for props 4. Add proper error handling ## Performance Optimization ### Current Optimizations - React.memo for node components - Debounced search - Lazy loading (can be added) - Code splitting (can be added) ### Potential Improvements 1. **Virtual scrolling** for large host lists 2. **Lazy loading** for routes 3. **Service worker** for offline support 4. **Caching** with React Query or SWR ## Testing Currently no tests included. Recommended setup: ```bash npm install -D vitest @testing-library/react @testing-library/jest-dom ``` Example test structure: ``` tests/ ├── components/ ├── hooks/ ├── pages/ └── utils/ ``` ## Deployment ### Build for Production ```bash npm run build ``` ### Static Hosting Upload `dist/` to: - Netlify - Vercel - GitHub Pages - AWS S3 + CloudFront ### Web Server Configuration Nginx example: ```nginx server { listen 80; server_name yourdomain.com; root /path/to/dist; location / { try_files $uri $uri/ /index.html; } location /api { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } ``` ## Environment Variables Create `.env.production` for production: ```env VITE_API_URL=https://api.yourdomain.com VITE_WS_URL=wss://api.yourdomain.com ``` ## Troubleshooting ### WebSocket Connection Issues - Check CORS settings on backend - Verify WebSocket URL - Check browser console for errors ### API Connection Issues - Verify backend is running - Check proxy configuration in `vite.config.ts` - Check network tab in browser dev tools ### Build Errors - Clear `node_modules` and reinstall - Check Node.js version (18+) - Update dependencies ## Code Quality ### ESLint ```bash npm run lint ``` ### TypeScript ```bash npx tsc --noEmit ``` ### Format (if Prettier is added) ```bash npx prettier --write src/ ``` ## Browser DevTools ### React DevTools Install extension for component inspection. ### Network Tab Monitor API calls and WebSocket messages. ### Console Check for errors and warnings. ## Contributing 1. Follow existing code style 2. Add TypeScript types for all new code 3. Test in multiple browsers 4. Update documentation ## Resources - [React Documentation](https://react.dev) - [React Flow Documentation](https://reactflow.dev) - [TailwindCSS Documentation](https://tailwindcss.com) - [Vite Documentation](https://vitejs.dev)