prvng_platform/control-center-ui/README.md

# Control Center UI - Audit Log Viewer

A comprehensive React-based audit log viewer for the Cedar Policy Engine with advanced search, real-time streaming, compliance reporting, and visualization capabilities.

## 🚀 Features

### 🔍 Advanced Search & Filtering
- **Multi-dimensional Filters**: Date range, users, actions, resources, severity, compliance frameworks
- **Real-time Search**: Debounced search with instant results
- **Saved Searches**: Save and reuse complex filter combinations
- **Quick Filters**: One-click access to common time ranges and filters
- **Correlation Search**: Find logs by request ID, session ID, or trace correlation

### 📊 High-Performance Data Display
- **Virtual Scrolling**: Handle millions of log entries with smooth scrolling
- **Infinite Loading**: Automatic pagination with optimized data fetching
- **Column Sorting**: Sort by any field with persistent state
- **Bulk Selection**: Select multiple logs for batch operations
- **Responsive Design**: Works seamlessly on desktop, tablet, and mobile

### 🔴 Real-time Streaming
- **WebSocket Integration**: Live log updates without page refresh
- **Connection Management**: Automatic reconnection with exponential backoff
- **Real-time Indicators**: Visual status of live connection
- **Message Queuing**: Handles high-volume log streams efficiently
- **Alert Notifications**: Critical events trigger immediate notifications

### 📋 Detailed Log Inspection
- **JSON Viewer**: Syntax-highlighted JSON with collapsible sections
- **Multi-tab Interface**: Overview, Context, Metadata, Compliance, Raw JSON
- **Sensitive Data Toggle**: Hide/show sensitive information
- **Copy Utilities**: One-click copying of IDs, values, and entire records
- **Deep Linking**: Direct URLs to specific log entries

### 📤 Export & Reporting
- **Multiple Formats**: CSV, JSON, PDF export with customizable fields
- **Template System**: Pre-built templates for different report types
- **Batch Export**: Export filtered results or selected logs
- **Progress Tracking**: Real-time export progress indication
- **Custom Fields**: Choose exactly which data to include

### 🛡️ Compliance Management
- **Framework Support**: SOC2, HIPAA, PCI DSS, GDPR compliance templates
- **Report Generation**: Automated compliance reports with evidence
- **Finding Tracking**: Track violations and remediation status
- **Attestation Management**: Digital signatures and certifications
- **Template Library**: Customizable report templates for different frameworks

### 🔗 Log Correlation & Tracing
- **Request Tracing**: Follow request flows across services
- **Session Analysis**: View all activity for a user session
- **Dependency Mapping**: Understand log relationships and causality
- **Timeline Views**: Chronological visualization of related events

### 📈 Visualization & Analytics
- **Dashboard Metrics**: Real-time statistics and KPIs
- **Timeline Charts**: Visual representation of log patterns
- **Geographic Distribution**: Location-based log analysis
- **Severity Trends**: Track security event patterns over time
- **User Activity**: Monitor user behavior and access patterns

## 🛠 Technology Stack

### Frontend Framework
- **React 18.3.1**: Modern React with hooks and concurrent features
- **TypeScript 5.5.4**: Type-safe development with advanced types
- **Vite 5.4.1**: Lightning-fast build tool and dev server

### UI Components & Styling
- **TailwindCSS 3.4.9**: Utility-first CSS framework
- **DaisyUI 4.4.19**: Beautiful component library built on Tailwind
- **Framer Motion 11.3.24**: Smooth animations and transitions
- **Lucide React 0.427.0**: Beautiful, customizable icons

### Data Management
- **TanStack Query 5.51.23**: Powerful data fetching and caching
- **TanStack Table 8.20.1**: Headless table utilities for complex data
- **TanStack Virtual 3.8.4**: Virtual scrolling for performance
- **Zustand 4.5.4**: Lightweight state management

### Forms & Validation
- **React Hook Form 7.52.2**: Performant forms with minimal re-renders
- **React Select 5.8.0**: Flexible select components with search

### Real-time & Networking
- **Native WebSocket API**: Direct WebSocket integration
- **Custom Hooks**: Reusable WebSocket management with reconnection

### Export & Reporting
- **jsPDF 2.5.1**: Client-side PDF generation
- **jsPDF AutoTable 3.8.2**: Table formatting for PDF reports
- **Native Blob API**: File download and export functionality

### Date & Time
- **date-fns 3.6.0**: Modern date utility library with tree shaking

## 📁 Project Structure

```
src/
├── components/audit/          # Audit log components
│   ├── AuditLogViewer.tsx    # Main viewer component
│   ├── SearchFilters.tsx     # Advanced search interface
│   ├── VirtualizedLogTable.tsx # High-performance table
│   ├── LogDetailModal.tsx    # Detailed log inspection
│   ├── ExportModal.tsx       # Export functionality
│   ├── ComplianceReportGenerator.tsx # Compliance reports
│   └── RealTimeIndicator.tsx # WebSocket status
├── hooks/                    # Custom React hooks
│   └── useWebSocket.ts       # WebSocket management
├── services/                 # API integration
│   └── api.ts               # Audit API client
├── types/                   # TypeScript definitions
│   └── audit.ts             # Audit-specific types
├── utils/                   # Utility functions
├── store/                   # State management
└── styles/                  # CSS and styling
```

## 🔧 Setup and Development

### Prerequisites
- **Node.js 18+** and **npm 9+**
- **Control Center backend** running on `http://localhost:8080`

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd control-center-ui

# Install dependencies
npm install

# Start development server
npm run dev
```

The application will be available at `http://localhost:3000`

### Building for Production

```bash
# Type check
npm run type-check

# Build for production
npm run build

# Preview production build
npm run preview
```

## 🌐 API Integration

The UI integrates with the Control Center backend and expects the following endpoints:

- `GET /audit/logs` - Fetch audit logs with filtering and pagination
- `GET /audit/logs/{id}` - Get specific log entry details
- `POST /audit/search` - Advanced search functionality
- `GET /audit/saved-searches` - Manage saved search queries
- `POST /audit/export` - Export logs in various formats (CSV, JSON, PDF)
- `GET /compliance/reports` - Compliance report management
- `POST /compliance/reports/generate` - Generate compliance reports
- `WS /audit/stream` - Real-time log streaming via WebSocket
- `GET /health` - Health check endpoint

### WebSocket Integration

Real-time log streaming is implemented using WebSocket connections:

```typescript
import { useWebSocket } from './hooks/useWebSocket';

const { isConnected, lastMessage } = useWebSocket({
  url: 'ws://localhost:8080/ws/audit',
  onNewAuditLog: (log) => {
    // Handle new log entry in real-time
    updateLogsList(log);
  }
});
```

## ✅ Features Implemented

### Core Audit Log Viewer System
- ✅ **Advanced Search Filters**: Multi-dimensional filtering with date range, users, actions, resources, severity, compliance frameworks
- ✅ **Virtual Scrolling Component**: High-performance rendering capable of handling millions of log entries
- ✅ **Real-time Log Streaming**: WebSocket integration with automatic reconnection and live status indicators
- ✅ **Detailed Log Modal**: Multi-tab interface with JSON syntax highlighting, sensitive data toggle, and copy utilities
- ✅ **Export Functionality**: Support for CSV, JSON, and PDF formats with customizable fields and templates
- ✅ **Saved Search Queries**: User preference system for saving and reusing complex search combinations

### Compliance & Security Features
- ✅ **Compliance Report Generator**: Automated report generation with SOC2, HIPAA, PCI DSS, and GDPR templates
- ✅ **Violation Tracking**: Remediation workflow system with task management and progress tracking
- ✅ **Timeline Visualization**: Chronological visualization of audit trails with correlation mapping
- ✅ **Request ID Correlation**: Cross-service request tracing and session analysis
- ✅ **Attestation Management**: Digital signature system for compliance certifications
- ✅ **Log Retention Management**: Archival policies and retention period management

### Performance & User Experience
- ✅ **Dashboard Analytics**: Real-time metrics including success rates, critical events, and compliance scores
- ✅ **Responsive Design**: Mobile-first design that works across all device sizes
- ✅ **Loading States**: Comprehensive loading indicators and skeleton screens
- ✅ **Error Handling**: Robust error boundaries with user-friendly error messages
- ✅ **Keyboard Shortcuts**: Accessibility features and keyboard navigation support

## 🎨 Styling and Theming

### TailwindCSS Configuration
The application uses a comprehensive TailwindCSS setup with:
- **DaisyUI Components**: Pre-built, accessible UI components
- **Custom Color Palette**: Primary, secondary, success, warning, error themes
- **Custom Animations**: Smooth transitions and loading states
- **Dark/Light Themes**: Automatic theme switching with system preference detection
- **Responsive Grid System**: Mobile-first responsive design

### Component Design System
- **Consistent Spacing**: Standardized margin and padding scales
- **Typography Scale**: Hierarchical text sizing and weights
- **Icon System**: Comprehensive icon library with consistent styling
- **Form Controls**: Validated, accessible form components
- **Data Visualization**: Charts and metrics with consistent styling

## 📱 Performance Optimization

### Virtual Scrolling
- Renders only visible rows for optimal performance
- Handles datasets with millions of entries smoothly
- Maintains smooth scrolling with momentum preservation
- Automatic cleanup of off-screen elements

### Efficient Data Fetching
- Infinite queries with intelligent pagination
- Aggressive caching with TanStack Query
- Optimistic updates for better user experience
- Background refetching for fresh data

### Bundle Optimization
- Code splitting by route and feature
- Tree shaking for minimal bundle size
- Lazy loading of heavy components
- Optimized production builds

## 🔒 Security Considerations

### Data Protection
- Sensitive data masking in UI components
- Secure WebSocket connections (WSS in production)
- Content Security Policy headers for XSS protection
- Input sanitization for search queries

### API Security
- JWT token authentication support (when implemented)
- Request rate limiting awareness
- Secure file downloads with proper headers
- CORS configuration for cross-origin requests

## 🚀 Deployment

### Docker Deployment
```dockerfile
FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: control-center-ui
spec:
  replicas: 3
  selector:
    matchLabels:
      app: control-center-ui
  template:
    metadata:
      labels:
        app: control-center-ui
    spec:
      containers:
      - name: control-center-ui
        image: control-center-ui:latest
        ports:
        - containerPort: 80
        env:
        - name: VITE_API_BASE_URL
          value: "https://api.example.com"
```

## 🤝 Contributing

### Development Guidelines
- Follow TypeScript strict mode conventions
- Use existing component patterns and design system
- Maintain accessibility standards (WCAG 2.1 AA)
- Add proper error boundaries for robust error handling
- Write meaningful commit messages following conventional commits

### Code Style
- Use Prettier for consistent code formatting
- Follow ESLint rules for code quality
- Use semantic HTML elements for accessibility
- Maintain consistent naming conventions
- Document complex logic with comments

## 📄 License

This project follows the same license as the parent Control Center repository.

## 🆘 Support

For questions, issues, or contributions:
1. Check existing issues in the repository
2. Review the comprehensive documentation
3. Create detailed bug reports or feature requests
4. Follow the established contribution guidelines

---

Built with ❤️ for comprehensive audit log management, compliance monitoring, and security analytics.