# Supervisor UI - Implementation Summary ## Overview A sophisticated, production-ready web application for managing Supervisor processes, built with Next.js 16 and Tailwind CSS 4. This implementation follows modern best practices and patterns from the pastel-ui project. ## Project Architecture ### Technology Stack - **Framework**: Next.js 16.0.3 (App Router, Standalone Output) - **React**: 19.2.0 with strict mode - **Styling**: Tailwind CSS 4.1.17 (CSS-first approach with OKLCH colors) - **State Management**: - TanStack Query 5.90.10 (server state) - Zustand 5.0.8 (client state - ready for future use) - **API Communication**: XML-RPC client for Supervisor - **Type Safety**: TypeScript 5.9.3 + Zod 3.25.76 - **UI Components**: Custom components with lucide-react icons - **Notifications**: Sonner 1.7.4 - **Package Manager**: pnpm 10.20.0 ### Key Features Implemented 1. **Real-time Monitoring** - Auto-refreshing process list (every 3 seconds) - System status updates (every 5 seconds) - Process state indicators with color-coded badges - Uptime tracking and formatting 2. **Process Control** - Start/Stop/Restart individual processes - Intelligent button states based on process status - Optimistic UI updates with React Query mutations - Toast notifications for all actions - Proper error handling with user feedback 3. **Modern Dashboard** - System status card with version info - Process statistics (total, running, stopped, fatal) - Quick action cards for navigation - Responsive grid layout - Smooth animations and transitions 4. **Backend API Proxy** - Next.js API routes for all Supervisor methods - Secure server-side XML-RPC communication - Environment-based configuration - Error handling and validation - RESTful API design 5. **Theme System** - Dark/light mode with system preference detection - Smooth theme transitions - OKLCH color space for perceptual uniformity - Custom color palette for process states - Persistent theme storage 6. **Docker Support** - Multi-stage Dockerfile for optimized builds - Node.js 20 Alpine base (lightweight) - Non-root user security - Health check endpoint - Docker Compose configuration - Arty integration ready ## File Structure ``` supervisor-ui/ ├── app/ │ ├── api/ │ │ ├── health/route.ts # Health check endpoint │ │ └── supervisor/ │ │ ├── system/route.ts # System info API │ │ └── processes/ │ │ ├── route.ts # All processes API │ │ └── [name]/ │ │ ├── route.ts # Single process info │ │ ├── start/route.ts # Start process │ │ ├── stop/route.ts # Stop process │ │ ├── restart/route.ts # Restart process │ │ └── logs/ │ │ ├── stdout/route.ts # Stdout logs │ │ └── stderr/route.ts # Stderr logs │ ├── config/page.tsx # Configuration page (placeholder) │ ├── logs/page.tsx # Logs page (placeholder) │ ├── processes/page.tsx # Process management page │ ├── globals.css # Tailwind CSS + theme system │ ├── layout.tsx # Root layout with providers │ └── page.tsx # Dashboard home ├── components/ │ ├── layout/ │ │ └── Navbar.tsx # Navigation bar with theme toggle │ ├── process/ │ │ ├── ProcessCard.tsx # Individual process card │ │ └── SystemStatus.tsx # System status display │ ├── providers/ │ │ ├── Providers.tsx # Combined provider wrapper │ │ └── ThemeProvider.tsx # Theme context provider │ └── ui/ │ ├── badge.tsx # Badge component │ ├── button.tsx # Button component │ └── card.tsx # Card components ├── lib/ │ ├── hooks/ │ │ └── useSupervisor.ts # React Query hooks │ ├── supervisor/ │ │ ├── client.ts # XML-RPC client class │ │ └── types.ts # TypeScript types + Zod schemas │ └── utils/ │ └── cn.ts # Class name utility ├── .dockerignore # Docker ignore patterns ├── .env.example # Environment variable template ├── .eslintrc.json # ESLint configuration ├── .gitignore # Git ignore patterns ├── .prettierrc # Prettier configuration ├── docker-compose.yml # Docker Compose setup ├── Dockerfile # Multi-stage production build ├── next.config.ts # Next.js configuration ├── package.json # Dependencies and scripts ├── postcss.config.mjs # PostCSS with Tailwind plugin ├── README.md # User documentation └── tsconfig.json # TypeScript configuration ``` ## API Routes Specification ### System Information - **GET** `/api/health` - Health check (returns status and timestamp) - **GET** `/api/supervisor/system` - Get system info (version, state, PID) ### Process Management - **GET** `/api/supervisor/processes` - List all processes - **GET** `/api/supervisor/processes/[name]` - Get single process info - **POST** `/api/supervisor/processes/[name]/start` - Start process - **POST** `/api/supervisor/processes/[name]/stop` - Stop process - **POST** `/api/supervisor/processes/[name]/restart` - Restart process ### Logs - **GET** `/api/supervisor/processes/[name]/logs/stdout` - Get stdout logs - **GET** `/api/supervisor/processes/[name]/logs/stderr` - Get stderr logs Query parameters for logs: - `offset` (default: -4096) - Byte offset for reading - `length` (default: 4096) - Number of bytes to read ## Configuration ### Environment Variables ```env # Supervisor Connection SUPERVISOR_HOST=localhost SUPERVISOR_PORT=9001 # Optional: Basic Authentication SUPERVISOR_USERNAME=user SUPERVISOR_PASSWORD=pass ``` ### Supervisor Setup Your `supervisord.conf` must enable the inet HTTP server: ```ini [inet_http_server] port = 127.0.0.1:9001 username = user ; Optional password = pass ; Optional ``` ## Development Workflow ### Local Development ```bash # Install dependencies pnpm install # Create environment file cp .env.example .env.local # Edit .env.local with your Supervisor connection details # Run development server pnpm dev # Open http://localhost:3000 ``` ### Code Quality ```bash # Type checking pnpm type-check # Linting pnpm lint pnpm lint:fix # Formatting pnpm format ``` ### Production Build ```bash # Build for production pnpm build # Start production server pnpm start ``` ## Docker Deployment ### Option 1: Docker Build & Run ```bash # Build image docker build -t supervisor-ui:latest . # Run container docker run -d \ --name supervisor-ui \ -p 3000:3000 \ -e SUPERVISOR_HOST=localhost \ -e SUPERVISOR_PORT=9001 \ supervisor-ui:latest ``` ### Option 2: Docker Compose ```bash # Start service docker-compose up -d # View logs docker-compose logs -f # Stop service docker-compose down ``` ### Option 3: Arty (Recommended for this environment) ```bash # Start service arty up -d supervisor-ui # Check status arty ps # View logs arty logs supervisor-ui # Stop service arty down supervisor-ui ``` ## Design System ### Color Palette (OKLCH) The application uses OKLCH color space for perceptually uniform colors: **Light Mode**: - Background: `oklch(98% 0 0)` - Nearly white - Foreground: `oklch(20% 0 0)` - Dark gray - Primary: `oklch(55% 0.15 220)` - Blue-green - Success: `oklch(60% 0.15 140)` - Green - Warning: `oklch(75% 0.15 90)` - Yellow - Destructive: `oklch(55% 0.20 25)` - Red **Dark Mode**: - Background: `oklch(15% 0.01 250)` - Very dark blue-gray - Foreground: `oklch(95% 0 0)` - Nearly white - Colors automatically adjusted for dark mode ### Process State Styling - **RUNNING**: Green background with success colors - **STOPPED/EXITED**: Gray muted colors - **STARTING/BACKOFF**: Yellow warning colors - **STOPPING**: Yellow warning colors - **FATAL**: Red destructive colors - **UNKNOWN**: Gray muted colors ### Typography - Font: Inter (Google Fonts) - Headings: Bold with gradient text effects - Body: Regular with good readability - Code/Mono: For PIDs, uptimes, versions ### Animations - `fade-in`: Gentle fade-in (0.3s) - `slide-up/down`: Slide animations (0.4s) - `scale-in`: Scale animation (0.2s) - `pulse-slow`: Slow pulsing (3s) - `spin-slow`: Slow rotation (3s) ## React Query Configuration ### Query Settings - **Stale Time**: 3 seconds (for real-time feel) - **Refetch on Window Focus**: Disabled - **Retry**: 2 attempts - **Refetch Intervals**: - System info: 5 seconds - Processes list: 3 seconds - Individual process: 3 seconds - Logs: 2 seconds (when enabled) ### Mutation Handling All mutations (start/stop/restart) automatically: 1. Show loading states on buttons 2. Display toast notifications on success/error 3. Invalidate related queries to trigger refetch 4. Update UI optimistically where possible ## Supervisor Client Implementation The XML-RPC client (`lib/supervisor/client.ts`) implements all Supervisor API methods: ### System Methods - `getAPIVersion()` - `getSupervisorVersion()` - `getIdentification()` - `getState()` - `getPID()` - `getSystemInfo()` - Combined method ### Process Control - `getAllProcessInfo()` - `getProcessInfo(name)` - `startProcess(name, wait)` - `stopProcess(name, wait)` - `restartProcess(name)` - Custom implementation - `signalProcess(name, signal)` - `signalProcessGroup(name, signal)` - `signalAllProcesses(signal)` ### Log Methods - `readProcessStdoutLog(name, offset, length)` - `readProcessStderrLog(name, offset, length)` - `tailProcessStdoutLog(name, offset, length)` - `tailProcessStderrLog(name, offset, length)` - `clearProcessLogs(name)` - `clearAllProcessLogs()` ### Configuration Methods - `reloadConfig()` - `addProcessGroup(name)` - `removeProcessGroup(name)` ### Control Methods - `shutdown()` - `restart()` - `sendProcessStdin(name, chars)` ## Type Safety ### Zod Schemas All API responses are validated with Zod schemas: - `ProcessInfoSchema` - Process information structure - `SupervisorStateInfoSchema` - System state structure - `ConfigInfoSchema` - Configuration structure - `ReloadConfigResultSchema` - Reload results ### TypeScript Types Comprehensive type definitions for: - Process states and state codes - Supervisor states - API responses and requests - Component props - Hook return types ## Future Enhancements ### Planned Features 1. **Log Viewer** - Real-time log tailing with auto-scroll - Search and filtering capabilities - Multi-process log aggregation - Log level highlighting - Download log files 2. **Configuration Management** - Reload configuration UI - Add/remove process groups - View full configuration - Validation before applying 3. **Advanced Features** - Process group batch operations - Keyboard shortcuts (start/stop/restart) - Charts for uptime and resource usage - Process dependency visualization - Event history timeline - Notifications for state changes 4. **Real-time Updates** - WebSocket support for push updates - Server-Sent Events (SSE) fallback - Reduce polling when WebSocket available 5. **Multi-Instance Support** - Connect to multiple Supervisor servers - Instance switcher in navbar - Dashboard showing all instances - Stored connections management ## Performance Optimizations ### Current Optimizations 1. **React Query Caching** - Intelligent cache invalidation - Stale-while-revalidate pattern - Background refetching 2. **Component Optimizations** - Proper React.memo usage where needed - Efficient re-render prevention - Loading skeletons for better UX 3. **Docker Build** - Multi-stage build reduces image size - Layer caching for faster rebuilds - Non-root user for security - Health checks for reliability 4. **Tailwind CSS** - CSS-first approach with v4 - Tree-shaking unused styles - Optimized for production ### Potential Optimizations 1. **Code Splitting** - Dynamic imports for heavy components - Route-based code splitting - Lazy loading for charts/graphs 2. **Image Optimization** - Next.js Image component - WebP format support - Lazy loading images 3. **Bundle Analysis** - Use webpack-bundle-analyzer - Identify large dependencies - Replace or optimize heavy libraries ## Security Considerations ### Implemented 1. **Backend Proxy Pattern** - No direct browser-to-Supervisor connection - Credentials stored server-side only - CSRF protection via Next.js 2. **Docker Security** - Non-root user in container - Minimal attack surface - Health checks for monitoring 3. **Type Safety** - Runtime validation with Zod - TypeScript strict mode - No unsafe type assertions ### Recommendations 1. **Authentication** - Add user authentication layer - Role-based access control - Session management 2. **HTTPS** - Use HTTPS in production - Secure cookie flags - HSTS headers 3. **Rate Limiting** - Implement rate limiting on API routes - Prevent DoS attacks - Monitor for abuse ## Testing Strategy ### Current State - Development testing completed - Manual UI testing performed - API route functionality verified ### Recommended Testing 1. **Unit Tests** - Supervisor client methods - Utility functions - Component logic 2. **Integration Tests** - API route handlers - React Query hooks - Component interactions 3. **E2E Tests** - Critical user flows - Process control operations - Error scenarios 4. **Tools to Add** - Vitest for unit tests - React Testing Library - Playwright for E2E tests ## Deployment Checklist ### Pre-Deployment - [ ] Set environment variables - [ ] Configure Supervisor connection - [ ] Test API connectivity - [ ] Review security settings - [ ] Enable HTTPS if possible - [ ] Set up monitoring/logging ### Docker Deployment - [ ] Build Docker image - [ ] Push to registry (if using one) - [ ] Configure docker-compose.yml - [ ] Set up persistent storage (if needed) - [ ] Configure networking - [ ] Set up reverse proxy (nginx/traefik) ### Post-Deployment - [ ] Verify health check endpoint - [ ] Test all process operations - [ ] Check real-time updates - [ ] Verify theme switching - [ ] Test on different browsers - [ ] Monitor error logs ## Maintenance ### Regular Tasks 1. **Dependency Updates** ```bash pnpm update --latest pnpm audit ``` 2. **Security Patches** - Monitor security advisories - Apply patches promptly - Test after updates 3. **Performance Monitoring** - Check response times - Monitor memory usage - Review error logs 4. **Backup** - No persistent data stored - Configuration in environment variables - Code in version control ## Troubleshooting ### Common Issues 1. **"Failed to connect to Supervisor"** - Check Supervisor is running - Verify inet_http_server enabled - Check SUPERVISOR_HOST and PORT - Test with `curl http://localhost:9001/RPC2` 2. **Theme Not Persisting** - Clear browser localStorage - Check for JavaScript errors - Verify ThemeProvider is wrapping app 3. **Processes Not Updating** - Check React Query devtools - Verify API routes returning data - Check browser console for errors 4. **Docker Container Won't Start** - Check health check endpoint - Review container logs - Verify environment variables - Check network connectivity ### Debug Mode Enable React Query DevTools by installing: ```bash pnpm add @tanstack/react-query-devtools ``` Add to `components/providers/Providers.tsx`: ```tsx import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; // In return statement: ``` ## Credits & References ### Inspired By - **pastel-ui**: Configuration patterns, Docker setup, and Tailwind CSS v4 usage - **Supervisor**: The excellent process control system this UI manages - **Next.js**: Modern React framework with excellent DX ### Built With - [Next.js](https://nextjs.org/) - React framework - [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS - [TanStack Query](https://tanstack.com/query/) - Async state management - [Zod](https://zod.dev/) - TypeScript-first validation - [Lucide React](https://lucide.dev/) - Beautiful icons - [Sonner](https://sonner.emilkowal.ski/) - Toast notifications ## License MIT License - Feel free to use and modify for your needs. --- **Last Updated**: November 23, 2025 **Version**: 0.1.0 **Status**: Production Ready (Core Features)