React UI migration

[aziolk-beyond]

Overview

This PR migrates the Claude Defense Kit from static HTML generation to a modern React Single Page Application (SPA) with Material-UI v7 and Beyond Identity's Machina design system.

🎯 Key Changes

Architecture

• Frontend: React 18 + TypeScript + Vite
• Backend: Express server serving built React app + REST API
• Design System: Material-UI v7 with custom Machina theme
• Build System: Dual TypeScript compilation (client + server)

Project Structure

src/
├── client/ # React SPA (new)
│ ├── components/ # Reusable UI components
│ ├── pages/ # Page components
│ ├── hooks/ # Custom React hooks
│ ├── services/ # API client
│ └── theme/ # Machina theme integration
└── server/ # Backend (reorganized)
├── analyzers/ # Risk analysis logic
├── scanners/ # Security scanners
└── server.ts # Express server

🎨 Design & UI

Machina Design System Integration

• Primary Color (Pine Green): #154545 - Used for technical elements, logos, and key UI text
• Secondary Color (Soft Teal): #D6F2F4 - Used for cards and backgrounds
• Typography: JetBrains Mono for technical/code elements, system fonts for body text
• Components: Custom themed MUI components following Machina guidelines

New Features

• ✅ Interactive security findings with live filtering (Risk Level, Type)
• ✅ Preview modal for configuration changes before applying
• ✅ One-click fix buttons with undo functionality
• ✅ Smooth scroll navigation with sidebar
• ✅ Real-time risk score calculation with visual indicators
• ✅ Warning icon on Risk Score chip when ≥50 (HIGH/CRITICAL)
• ✅ Clickable logo to scroll to top

Responsive Design

Fully responsive layouts with breakpoints:

• Mobile (xs): Single column, stacked filters, hidden sidebar
• Tablet (sm/md): 2-3 column grids, responsive filters
• Desktop (lg+): Full 5-column grid, sidebar navigation, all features visible

UI Polish

• Pine Green text/icons in "What We Scanned" cards
• JetBrains Mono monospace font for technical titles
• 4-tier risk badges (critical/high/medium/low)
• Critical risks display with warning color (yellow)
• Smooth animations and transitions
• WCAG 2.0 AA compliant color contrast

🔧 Technical Implementation

Frontend Stack

• React 18: Modern React with hooks
• Material-UI v7: Latest MUI with improved theming
• TypeScript: Full type safety
• Vite: Fast dev server and optimized builds
• React Router: Client-side routing

Backend Updates

• Express server serves both static React build and API endpoints
• Maintained all existing scan/analysis functionality
• RESTful API: /api/scan, /api/fix, /api/undo
• No changes to core security scanning logic

State Management

• React hooks (useState, useEffect) for local state
• Custom hooks: useScanData, useToast
• API service layer for backend communication

📊 Risk Score Logic

Weighted scoring system (0-100):

• MCP Servers: Critical (25), High (15), Medium (8), Low (3)
• Sensitive Files: Critical (15), High (10), Medium (5), Low (2)
• Capabilities: Shell (20), Database (12), Package Install (10), Network (8)
• Categories: Critical (≥75), High (50-74), Medium (25-49), Low (<25)

🧪 Testing Considerations

• Test responsive layouts on mobile/tablet/desktop
• Verify fix/undo functionality with various security issues
• Test filtering by risk level and issue type
• Confirm sidebar navigation and scroll behavior
• Validate API endpoints return correct data
• Check accessibility with screen readers

🚀 Deployment Notes

Build Process

npm run build        # Builds both client and server
npm start           # Production server
npm run dev         # Development with hot-reload
Environment
Node.js 18+ required
Port 3847 for production server
Port 5173 for Vite dev server (dev only)

🔄 Migration Impact
Breaking Changes
❌ Removed static HTML report generation
❌ Removed old terminal-based reporters
✅ Replaced with interactive React SPA
Backward Compatibility
✅ CLI commands unchanged
✅ Scan logic unchanged
✅ Configuration format unchanged
✅ All security features maintained
📝 Additional Notes

Why This Migration?
Better UX: Interactive UI vs static HTML
Modern Stack: React/MUI vs vanilla JS
Design System: Consistent with Beyond Identity brand
Maintainability: Component-based architecture
Extensibility: Easy to add new features

🤝 Review Checklist
 Code follows TypeScript best practices
 All files use Machina design tokens (no hardcoded colors)
 Responsive design works on all breakpoints
 Accessibility standards met (WCAG 2.0 AA)
 No console errors or warnings
 Build succeeds without errors
 
Co-Authored-By: Claude Sonnet 4.5