Add technical documentation and refactor components for machine status monitoring dashboard

Author: MarkHershey

DOCS.md

@@ -0,0 +1,123 @@
+# Technical Documentation
+
+## Overview
+
+**MXStatus** is a React-based web dashboard for monitoring the status of multiple machines, with a focus on GPU, user, and network information. The application is designed for clarity, responsiveness, and a "hacker" aesthetic, using a custom dark theme and modern UI/UX practices.
+
+---
+
+## Technical Design Choices
+
+- **Framework**: Built with React (v17), using functional components and React Hooks for state and effect management.
+- **State Management**: Local state is managed via React's `useState` and `useEffect`. LocalStorage is used for persisting user preferences (e.g., refresh interval, view key, display options).
+- **Data Fetching**: Uses `axios` for HTTP requests to a backend API, with support for custom server endpoints and view keys.
+- **Componentization**: The UI is highly modular, with reusable components for cards, badges, copyable text, and more.
+- **Responsiveness**: Layouts and controls are responsive, adapting to mobile and desktop via CSS media queries.
+- **Performance**: Includes a loading animation and ensures a minimum loading time for smooth transitions. Auto-refresh is supported with configurable intervals.
+- **Accessibility**: Uses semantic HTML and accessible form controls, with focus and hover states for interactive elements.
+
+---
+
+## Main Libraries Used
+
+- **React**: Core UI framework.
+- **axios**: For HTTP requests to the backend API.
+- **react-sortablejs** and **sortablejs**: (Listed as dependencies, but not directly used in the main code; possibly for future drag-and-drop features.)
+- **Bootstrap 5**: Included via CDN for grid and utility classes, but most styling is custom.
+- **Google Fonts**: "Source Code Pro" (monospace) and "Inter" (UI font) for a modern, technical look.
+- **Testing**: `@testing-library/react`, `@testing-library/jest-dom`, and `@testing-library/user-event` for unit and integration tests.
+- **web-vitals**: For measuring and reporting performance metrics.
+
+> **Note:** TailwindCSS is listed as a dependency but is not actually used or configured in the codebase. All styling is custom via CSS.
+
+---
+
+## Styling Choices
+
+- **Custom Theme**: All colors, spacing, and typography are defined via CSS variables in `index.css` (e.g., `--hacker-bg`, `--hacker-text-accent`).
+- **Dark Mode**: The default and only theme is a dark, "hacker" style with neon green accents (`#00ff41`), inspired by terminal UIs.
+- **Responsive Design**: Extensive use of media queries for font sizes, spacing, and layout adjustments on mobile and desktop.
+- **Animations**: Subtle animations for loading, hover, and status indicators (e.g., pulse for online status, animated loading spinner).
+- **Touch-Friendly**: Larger touch targets and spacing for mobile usability.
+- **Custom Components**: Custom cards, badges, and containers with consistent border radius, shadows, and transitions.
+- **Minimal Bootstrap**: Bootstrap is loaded but only lightly used; most layout and style is custom.
+
+---
+
+## Website Component Structure
+
+### Top-Level
+
+- **App.js**: Root component. Renders the main page (`PageMain`) and a footer.
+
+### Main Page (`PageMain.js`)
+
+- **CodeFlowBackground**: Animated code lines in the background for the welcome screen.
+- **LoadingAnimation**: Full-screen loading spinner and status.
+- **ErrorMessage**: Card for displaying connection or data errors.
+- **Control Center**: UI for entering the view key, selecting server, toggling auto-refresh, and hiding offline machines.
+- **Servers Grid**: Renders a list of `MachineCard` components, one for each machine.
+
+### Machine Display (`MachineCard.js`)
+
+- **Header**: Shows hostname, online/offline badge, GPU count, and a details toggle.
+- **Details Section**: Expands to show:
+  - **Last seen** and **uptime** (with copy-to-clipboard).
+  - **GPU Information**: Rendered via `GPUv2` (one per GPU).
+  - **User Information**: Rendered via `UsersLine` (online/offline users).
+  - **IP Addresses**: Rendered via `IP` and `SingleIP` (with copy-to-clipboard).
+- **Status Indicators**: Color-coded badges for online/offline, GPU presence, and more.
+
+### Supporting Components
+
+- **GPUv2**: Shows GPU utilization, temperature, memory usage, and model, with color-coded bars and badges.
+- **UsersLine**: Lists online and offline users with `UserBadge` for each.
+- **UserBadge**: Visual badge for a user, color-coded by online status.
+- **CopyableText**: Inline text with click-to-copy and feedback animation.
+- **DisplayPercent / DisplayRAM / DisplayTemp**: Utility components for formatting and color-coding percentages, RAM, and temperature.
+- **Footer**: Simple, centered copyright.
+
+---
+
+## File Structure (Key Files)
+
+```
+mxstatus/
+  src/
+    App.js
+    App.css
+    index.js
+    index.css
+    components/
+      PageMain.js
+      MachineCard.js
+      GPUv2.js
+      UsersLine.js
+      UserBadge.js
+      CopyableText.js
+      DisplayPercent.js
+      DisplayRAM.js
+      DisplayTemp.js
+      IP.js
+      SingleIP.js
+      Footer.js
+```
+
+---
+
+## Notable UI/UX Features
+
+- **Animated Welcome Screen**: With code flow background and smooth transitions.
+- **Copy-to-Clipboard**: For hostnames, IPs, and other key data.
+- **Auto-Refresh**: User-configurable, with persistent settings.
+- **Offline Filtering**: Option to hide offline machines for clarity.
+- **Mobile-First**: All controls and cards are touch-friendly and responsive.
+- **Status Feedback**: Real-time online/offline, GPU, and user status with color and animation.
+
+---
+
+## Summary
+
+MXStatus is a modern, highly-customized React dashboard for machine status monitoring, with a strong focus on UX, clarity, and a distinctive "hacker" aesthetic. The codebase is modular, maintainable, and ready for extension (e.g., more metrics, drag-and-drop, or additional views).
+
+---

mxstatus/src/App.css

@@ -95,7 +95,7 @@
   padding: 0.75rem;
   margin-bottom: 0.75rem;
   transition: var(--hacker-transition);
-  cursor: pointer;
+  /* cursor: pointer; */
 }
 
 .hacker-card:hover {
@@ -1059,3 +1059,18 @@ footer:hover {
   background-color: rgba(0, 255, 65, 0.02);
   border-radius: 0.25rem;
 }
+
+.details-anim {
+  max-height: 0;
+  opacity: 0;
+  overflow: hidden;
+  transition: max-height 0.4s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.3s;
+}
+.details-anim.expanded {
+  max-height: 1000px;
+  opacity: 1;
+}
+.details-anim.collapsed {
+  max-height: 0;
+  opacity: 0;
+}

mxstatus/src/components/GPU.js

@@ -5,7 +5,7 @@ import DisplayTemp from './DisplayTemp'
 import DisplayRAM from './DisplayRAM'
 import CopyableText from './CopyableText'
 
-const GPUv2 = props => {
+const GpuCard = props => {
     const getUtilizationColor = (percent) => {
         if (percent < 0.3) return 'var(--hacker-info)'
         if (percent < 0.7) return 'var(--hacker-warning)'
@@ -279,11 +279,11 @@ const GPUv2 = props => {
     )
 }
 
-GPUv2.propTypes = {
+GpuCard.propTypes = {
     "data": PropTypes.object
 }
 
-GPUv2.defaultProps = {
+GpuCard.defaultProps = {
     "data": {
         "index": 0,
         "gpu_name": "GeForce RTX xxxx xx",
@@ -295,4 +295,4 @@ GPUv2.defaultProps = {
     }
 }
 
-export default GPUv2
+export default GpuCard

mxstatus/src/components/GPUv2.js mxstatus/src/components/GpuCard.jsmxstatus/src/components/GPUv2.js renamed to mxstatus/src/components/GpuCard.js

@@ -2,13 +2,13 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import { useState } from 'react'
 import IP from './IP'
-import GPUv2 from './GPUv2'
+import GpuCard from './GpuCard'
 import UsersLine from './UsersLine'
 import DisplayPercent from './DisplayPercent'
 import DisplayRAM from './DisplayRAM'
 import CopyableText from './CopyableText'
 
-const WorkstationV2 = props => {
+const MachineCard = props => {
 
     // const secondsToHms = (d) => {
     //     d = Number(d);
@@ -86,15 +86,6 @@ const WorkstationV2 = props => {
         })
     }
 
-    // Handle card click to toggle details
-    const handleCardClick = (e) => {
-        // Don't toggle if clicking on interactive elements
-        if (e.target.closest('button') || e.target.closest('.CopyableText') || e.target.closest('input') || e.target.closest('.process-item')) {
-            return
-        }
-        handleShowDetails()
-    }
-
     // Handle click on interactive elements to prevent bubbling
     const handleInteractiveClick = (e) => {
         e.stopPropagation()
@@ -127,7 +118,7 @@ const WorkstationV2 = props => {
         <div className="hacker-card fade-in" style={{
             borderLeft: `4px solid ${getStatusColor()}`,
             opacity: isOnline() ? 1 : 0.7
-        }} onClick={handleCardClick}>
+        }} >
             <div className="server-header d-flex align-items-center justify-content-between mb-2">
                 <div className="d-flex align-items-center gap-2">
                     <h3 className="mb-0" style={{
@@ -183,12 +174,12 @@ const WorkstationV2 = props => {
                             background: 'transparent'
                         }}
                     >
-                        {showDetails ? 'HIDE' : 'DETAILS'}
+                        {showDetails ? 'HIDE DETAILS' : 'DETAILS'}
                     </button>
                 </div>
             </div>
 
-            {showDetails && (
+            <div className={`details-anim${showDetails ? ' expanded' : ' collapsed'}`}>
                 <div className="server-details" style={{
                     borderTop: '1px solid var(--hacker-border)',
                     paddingTop: '0.75rem',
@@ -256,11 +247,11 @@ const WorkstationV2 = props => {
                         </div>
                     </div>
                 </div>
-            )}
+            </div>
 
             {isEmpty(props.data.gpu_status) || !showDetails ? null :
                 <div className="gpu-section mt-2">
-                    {props.data.gpu_status.map((gpu_data, idx) => <GPUv2 key={idx} data={gpu_data} />)}
+                    {props.data.gpu_status.map((gpu_data, idx) => <GpuCard key={idx} data={gpu_data} />)}
                 </div>
             }
 
@@ -610,14 +601,14 @@ const WorkstationV2 = props => {
     )
 }
 
-WorkstationV2.propTypes = {
+MachineCard.propTypes = {
     "data": PropTypes.object,
 }
 
-WorkstationV2.defaultProps = {
+MachineCard.defaultProps = {
     "data": {
         "gpu_status": []
     }
 }
 
-export default WorkstationV2
+export default MachineCard

mxstatus/src/components/WorkstationV2.js mxstatus/src/components/MachineCard.jsmxstatus/src/components/WorkstationV2.js renamed to mxstatus/src/components/MachineCard.js

@@ -2,7 +2,7 @@ import React from 'react'
 import { useState, useEffect, useRef } from 'react'
 
 // import Workstation from "./Workstation"
-import WorkstationV2 from "./WorkstationV2"
+import MachineCard from "./MachineCard"
 
 import axios from "axios";
 
@@ -1089,7 +1089,7 @@ const PageMain = () => {
                             <div className="servers-grid">
                                 {
                                     filteredMachines.map((data, index) => {
-                                        return <WorkstationV2 data={data} key={index} />
+                                        return <MachineCard data={data} key={index} />
                                     })
                                 }
                             </div>