@diagramers/admin/README.md

Diagramers Admin Template - React starter for admin dashboards.

# @diagramers/admin

A comprehensive React-based admin dashboard template with modern UI/UX, extensive customization options, and full integration with the Diagramers ecosystem. Built with React 18, TypeScript, and a modular architecture for rapid development of professional admin interfaces.

## 🚀 Features

### Core Framework
- **React 18** - Latest React with concurrent features and hooks
- **TypeScript** - Full TypeScript support with strict typing
- **Modern Build System** - Webpack 5 with hot reload and optimization
- **CSS-in-JS** - Styled-components and CSS modules support
- **Responsive Design** - Mobile-first responsive layout system

### UI/UX Components
- **Modern Dashboard** - Clean, professional admin interface
- **Component Library** - 100+ reusable UI components
- **Data Tables** - Advanced tables with sorting, filtering, pagination
- **Charts & Analytics** - Interactive charts (Line, Bar, Pie, Area)
- **Form Components** - Dynamic forms with validation
- **Modal System** - Flexible modal and dialog components
- **Navigation** - Sidebar navigation with collapsible menus
- **Breadcrumbs** - Contextual navigation breadcrumbs
- **Loading States** - Skeleton loaders and progress indicators

### Authentication & Security
- **JWT Authentication** - Secure token-based authentication
- **Role-Based Access Control** - Granular permission system
- **Session Management** - Secure session handling
- **Password Policies** - Configurable password requirements
- **Multi-factor Authentication** - Enhanced security options
- **OAuth Integration** - Social login providers
- **SSO Support** - Single Sign-On integration

### Data Management
- **CRUD Operations** - Complete Create, Read, Update, Delete
- **Real-time Updates** - WebSocket integration for live data
- **Data Validation** - Client-side and server-side validation
- **File Upload** - Drag & drop file upload with progress
- **Image Management** - Image upload, cropping, and optimization
- **Export/Import** - CSV, Excel, PDF export capabilities
- **Bulk Operations** - Mass data operations

### Communication Features
- **Email Integration** - Email composition and management
- **SMS Integration** - SMS sending and management
- **Push Notifications** - Real-time push notifications
- **In-app Messaging** - Internal messaging system
- **Notification Center** - Centralized notification management
- **Webhook Management** - Webhook configuration and monitoring

### Analytics & Reporting
- **Dashboard Analytics** - Key performance indicators
- **Custom Reports** - Configurable reporting system
- **Data Visualization** - Interactive charts and graphs
- **Export Reports** - PDF and Excel report generation
- **Scheduled Reports** - Automated report delivery
- **Real-time Metrics** - Live data monitoring

### User Management
- **User Profiles** - Complete user profile management
- **Role Management** - User role assignment and permissions
- **Activity Tracking** - User activity monitoring
- **Session Management** - Active session tracking
- **User Analytics** - User behavior analytics
- **Bulk User Operations** - Mass user management

### System Administration
- **System Settings** - Application configuration
- **User Management** - Admin user management
- **Audit Logs** - System activity logging
- **Backup Management** - Data backup and restore
- **System Health** - Application health monitoring
- **Performance Monitoring** - System performance metrics

### Customization & Theming
- **Theme System** - Multiple color themes and dark mode
- **Custom Branding** - Logo, colors, and branding customization
- **Layout Options** - Flexible layout configurations
- **Component Styling** - Customizable component styles
- **Internationalization** - Multi-language support
- **Accessibility** - WCAG 2.1 compliance

### Development Tools
- **Hot Reload** - Instant code changes reflection
- **TypeScript Support** - Full TypeScript integration
- **ESLint & Prettier** - Code quality and formatting
- **Testing Framework** - Jest and React Testing Library
- **Storybook** - Component documentation and testing
- **Build Optimization** - Production build optimization

## 📦 Installation

### Using CLI (Recommended)
```bash
# Install CLI globally
npm install -g @diagramers/cli

# Create new admin project
diagramers init admin my-admin-dashboard

# Navigate to project
cd my-admin-dashboard

# Install dependencies
npm install --legacy-peer-deps

# Start development server
npm start
```

### Manual Installation
```bash
# Install package
npm install @diagramers/admin

# Initialize project
npx diagramers-admin-init my-admin-dashboard

# Navigate to project
cd my-admin-dashboard

# Install dependencies
npm install --legacy-peer-deps

# Start development server
npm start
```

## 🛠️ Quick Start

### 1. Project Setup
```bash
# Create new admin project
diagramers init admin my-admin-dashboard

# Navigate to project
cd my-admin-dashboard

# Configure environment variables
cp .env.example .env
# Edit .env with your API URL and configuration

# Install dependencies
npm install --legacy-peer-deps

# Start development server
npm start
```

### 2. Configuration
```bash
# Update API configuration in src/config.js
export const SERVICE_URL = 'http://localhost:3000';
export const REACT_HELMET_PROPS = {
  defaultTitle: 'My Admin Dashboard',
  titleTemplate: '%s | My Admin Dashboard',
};
```

### 3. Customization
```bash
# Replace logo in public/img/logo/
# Update favicon in public/img/favicon/
# Customize theme in src/sass/themes/
# Modify navigation in src/layout/nav/
```

### 4. Development
```bash
# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint
```

## 🔧 Configuration

### Environment Variables
```bash
# API Configuration
REACT_APP_API_URL=http://localhost:3000
REACT_APP_PROJECT_NAME=My Admin Dashboard

# Authentication
REACT_APP_JWT_SECRET=your-jwt-secret
REACT_APP_AUTH_PROVIDER=internal

# Features
REACT_APP_ENABLE_ANALYTICS=true
REACT_APP_ENABLE_NOTIFICATIONS=true
REACT_APP_ENABLE_REAL_TIME=true

# External Services
REACT_APP_SOCKET_URL=ws://localhost:3000
REACT_APP_SENTRY_DSN=your-sentry-dsn
```

### API Configuration
```javascript
// src/config.js
export const SERVICE_URL = process.env.REACT_APP_API_URL || 'http://localhost:3000';
export const REACT_HELMET_PROPS = {
  defaultTitle: process.env.REACT_APP_PROJECT_NAME || 'Admin Dashboard',
  titleTemplate: `%s | ${process.env.REACT_APP_PROJECT_NAME || 'Admin Dashboard'}`,
};
```

### Theme Configuration
```scss
// src/sass/themes/_custom.scss
:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --success-color: #28a745;
  --danger-color: #dc3545;
  --warning-color: #ffc107;
  --info-color: #17a2b8;
  --light-color: #f8f9fa;
  --dark-color: #343a40;
}
```

## 📚 Component Library

### Layout Components
```jsx
import { Layout, Sidebar, Header, Footer } from '@diagramers/admin';

// Main layout
<Layout>
  <Sidebar />
  <div className="main-content">
    <Header />
    <main>{children}</main>
    <Footer />
  </div>
</Layout>
```

### Data Components
```jsx
import { DataTable, DataGrid, DataChart } from '@diagramers/admin';

// Data table with sorting and filtering
<DataTable
  data={products}
  columns={productColumns}
  sortable
  filterable
  pagination
/>

// Interactive chart
<DataChart
  type="line"
  data={chartData}
  options={chartOptions}
/>
```

### Form Components
```jsx
import { Form, Input, Select, Button } from '@diagramers/admin';

// Dynamic form
<Form onSubmit={handleSubmit}>
  <Input name="name" label="Name" required />
  <Select name="category" label="Category" options={categories} />
  <Button type="submit">Save</Button>
</Form>
```

### Navigation Components
```jsx
import { Navigation, Menu, Breadcrumb } from '@diagramers/admin';

// Sidebar navigation
<Navigation>
  <Menu items={menuItems} />
</Navigation>

// Breadcrumb navigation
<Breadcrumb items={breadcrumbItems} />
```

## 🔐 Authentication

### Login Component
```jsx
import { LoginForm } from '@diagramers/admin';

<LoginForm
  onLogin={handleLogin}
  providers={['internal', 'google', 'github']}
  rememberMe
  forgotPassword
/>
```

### Protected Routes
```jsx
import { ProtectedRoute, useAuth } from '@diagramers/admin';

// Protected route component
<ProtectedRoute
  path="/dashboard"
  component={Dashboard}
  roles={['admin', 'user']}
  permissions={['read:dashboard']}
/>

// Use auth hook
const { user, isAuthenticated, login, logout } = useAuth();
```

### Role-Based Access
```jsx
import { usePermissions } from '@diagramers/admin';

const { hasPermission, hasRole } = usePermissions();

// Check permissions
{hasPermission('create:users') && (
  <Button onClick={createUser}>Create User</Button>
)}

// Check roles
{hasRole('admin') && (
  <AdminPanel />
)}
```

## 📊 Dashboard Features

### Analytics Dashboard
```jsx
import { AnalyticsDashboard } from '@diagramers/admin';

<AnalyticsDashboard
  metrics={[
    { title: 'Total Users', value: 1250, change: '+12%' },
    { title: 'Revenue', value: '$45,230', change: '+8%' },
    { title: 'Orders', value: 89, change: '+5%' },
  ]}
  charts={[
    { type: 'line', data: revenueData, title: 'Revenue Trend' },
    { type: 'bar', data: userData, title: 'User Growth' },
  ]}
/>
```

### Data Management
```jsx
import { DataManager } from '@diagramers/admin';

<DataManager
  endpoint="/api/users"
  columns={userColumns}
  actions={['create', 'edit', 'delete', 'export']}
  filters={['search', 'role', 'status']}
  bulkActions={['activate', 'deactivate', 'delete']}
/>
```

### Real-time Updates
```jsx
import { useWebSocket } from '@diagramers/admin';

const { data, isConnected } = useWebSocket('/api/notifications');

// Real-time notifications
{data.map(notification => (
  <Notification key={notification.id} {...notification} />
))}
```

## 🎨 Customization

### Theme Customization
```scss
// src/sass/themes/_custom.scss
:root {
  // Primary colors
  --primary-color: #007bff;
  --primary-hover: #0056b3;
  --primary-light: #e3f2fd;
  
  // Secondary colors
  --secondary-color: #6c757d;
  --secondary-hover: #545b62;
  
  // Success colors
  --success-color: #28a745;
  --success-hover: #1e7e34;
  
  // Danger colors
  --danger-color: #dc3545;
  --danger-hover: #c82333;
  
  // Typography
  --font-family: 'Inter', sans-serif;
  --font-size-base: 1rem;
  --line-height-base: 1.5;
  
  // Spacing
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 3rem;
}
```

### Component Styling
```scss
// src/sass/components/_custom.scss
.custom-button {
  background: var(--primary-color);
  border: none;
  border-radius: 8px;
  padding: 12px 24px;
  font-weight: 600;
  transition: all 0.2s ease;
  
  &:hover {
    background: var(--primary-hover);
    transform: translateY(-1px);
  }
}

.custom-card {
  background: white;
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  padding: 24px;
  margin-bottom: 24px;
}
```

### Layout Customization
```jsx
// src/layout/Layout.js
import { Layout, Sidebar, Header } from '@diagramers/admin';

const CustomLayout = ({ children }) => (
  <Layout className="custom-layout">
    <Sidebar 
      className="custom-sidebar"
      logo="/img/logo/custom-logo.svg"
      menuItems={customMenuItems}
    />
    <div className="main-content">
      <Header 
        className="custom-header"
        userMenu={customUserMenu}
        notifications={customNotifications}
      />
      <main className="content-area">
        {children}
      </main>
    </div>
  </Layout>
);
```

## 🔌 API Integration

### API Service Setup
```javascript
// src/services/api.js
import { ApiService } from '@diagramers/admin';

const api = new ApiService({
  baseURL: process.env.REACT_APP_API_URL,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Add request interceptor for authentication
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Add response interceptor for error handling
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Handle unauthorized access
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export default api;
```

### Data Fetching
```jsx
import { useApi } from '@diagramers/admin';

const { data, loading, error, refetch } = useApi('/api/users');

// With parameters
const { data: users } = useApi('/api/users', {
  params: { page: 1, limit: 10, search: 'john' }
});

// With mutations
const { mutate, isLoading } = useApi('/api/users', {
  method: 'POST',
  onSuccess: () => {
    // Handle success
  },
  onError: (error) => {
    // Handle error
  },
});
```

### Real-time Integration
```jsx
import { useWebSocket } from '@diagramers/admin';

const { data, isConnected, send } = useWebSocket('/api/notifications', {
  onMessage: (message) => {
    // Handle incoming messages
    console.log('Received:', message);
  },
  onConnect: () => {
    console.log('Connected to WebSocket');
  },
  onDisconnect: () => {
    console.log('Disconnected from WebSocket');
  },
});

// Send message
send({ type: 'notification', data: { message: 'Hello!' } });
```

## 📱 Responsive Design

### Mobile-First Approach
```scss
// src/sass/layout/_responsive.scss
.container {
  width: 100%;
  padding: 0 16px;
  margin: 0 auto;
  
  @media (min-width: 576px) {
    max-width: 540px;
  }
  
  @media (min-width: 768px) {
    max-width: 720px;
  }
  
  @media (min-width: 992px) {
    max-width: 960px;
  }
  
  @media (min-width: 1200px) {
    max-width: 1140px;
  }
}

.sidebar {
  @media (max-width: 768px) {
    transform: translateX(-100%);
    position: fixed;
    z-index: 1000;
    
    &.open {
      transform: translateX(0);
    }
  }
}
```

### Touch-Friendly Components
```jsx
import { TouchableButton, SwipeableCard } from '@diagramers/admin';

// Touch-friendly button
<TouchableButton
  size="large"
  onPress={handlePress}
  feedback="haptic"
>
  Press Me
</TouchableButton>

// Swipeable card
<SwipeableCard
  onSwipeLeft={() => handleDelete()}
  onSwipeRight={() => handleEdit()}
>
  <CardContent />
</SwipeableCard>
```

## 🧪 Testing

### Component Testing
```jsx
import { render, screen, fireEvent } from '@testing-library/react';
import { LoginForm } from '@diagramers/admin';

test('login form submits with correct data', () => {
  const mockOnLogin = jest.fn();
  
  render(<LoginForm onLogin={mockOnLogin} />);
  
  fireEvent.change(screen.getByLabelText('Email'), {
    target: { value: 'test@example.com' },
  });
  
  fireEvent.change(screen.getByLabelText('Password'), {
    target: { value: 'password123' },
  });
  
  fireEvent.click(screen.getByRole('button', { name: /login/i }));
  
  expect(mockOnLogin).toHaveBeenCalledWith({
    email: 'test@example.com',
    password: 'password123',
  });
});
```

### Integration Testing
```jsx
import { render, screen, waitFor } from '@testing-library/react';
import { DataTable } from '@diagramers/admin';

test('data table loads and displays data', async () => {
  const mockData = [
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
  ];
  
  render(<DataTable data={mockData} />);
  
  await waitFor(() => {
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('Jane Smith')).toBeInTheDocument();
  });
});
```

## 🚀 Deployment

### Build Configuration
```javascript
// webpack.config.js
module.exports = {
  mode: 'production',
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
        },
      },
    },
  },
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
  },
};
```

### Environment-Specific Builds
```bash
# Development build
npm run build:dev

# Staging build
npm run build:staging

# Production build
npm run build:prod

# Analyze bundle
npm run build:analyze
```

### Docker Deployment
```dockerfile
# Dockerfile
FROM node:18-alpine as builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build:prod

FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

## 📊 Performance Optimization

### Code Splitting
```jsx
import { lazy, Suspense } from 'react';

// Lazy load components
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Users = lazy(() => import('./pages/Users'));
const Settings = lazy(() => import('./pages/Settings'));

// Suspense wrapper
<Suspense fallback={<LoadingSpinner />}>
  <Dashboard />
</Suspense>
```

### Memoization
```jsx
import { useMemo, useCallback } from 'react';

// Memoize expensive calculations
const expensiveValue = useMemo(() => {
  return data.reduce((sum, item) => sum + item.value, 0);
}, [data]);

// Memoize callbacks
const handleClick = useCallback((id) => {
  // Handle click
}, []);
```

### Image Optimization
```jsx
import { OptimizedImage } from '@diagramers/admin';

<OptimizedImage
  src="/img/avatar.jpg"
  alt="User Avatar"
  width={100}
  height={100}
  lazy
  placeholder="/img/avatar-placeholder.jpg"
/>
```

## 🔒 Security

### Security Headers
```javascript
// public/index.html
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';">
<meta http-equiv="X-Content-Type-Options" content="nosniff">
<meta http-equiv="X-Frame-Options" content="DENY">
<meta http-equiv="X-XSS-Protection" content="1; mode=block">
```

### Input Validation
```jsx
import { useForm } from '@diagramers/admin';

const { register, handleSubmit, errors } = useForm();

<form onSubmit={handleSubmit(onSubmit)}>
  <input
    {...register('email', {
      required: 'Email is required',
      pattern: {
        value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
        message: 'Invalid email address',
      },
    })}
  />
  {errors.email && <span>{errors.email.message}</span>}
</form>
```

### XSS Prevention
```jsx
import { sanitizeHtml } from '@diagramers/admin';

// Sanitize user input
const sanitizedContent = sanitizeHtml(userInput);

// Safe rendering
<div dangerouslySetInnerHTML={{ __html: sanitizedContent }} />
```

## 📚 Documentation

### Component Documentation
```jsx
/**
 * @component DataTable
 * @description A responsive data table with sorting, filtering, and pagination
 * @example
 * ```jsx
 * <DataTable
 *   data={users}
 *   columns={userColumns}
 *   sortable
 *   filterable
 *   pagination
 * />
 * ```
 */
```

### API Documentation
```javascript
/**
 * @api {get} /api/users Get users
 * @apiName GetUsers
 * @apiGroup Users
 * @apiParam {Number} page Page number
 * @apiParam {Number} limit Items per page
 * @apiParam {String} search Search query
 * @apiSuccess {Object[]} users List of users
 * @apiSuccess {String} users.id User ID
 * @apiSuccess {String} users.name User name
 * @apiSuccess {String} users.email User email
 */
```

## 🤝 Contributing

### Development Setup
```bash
# Clone repository
git clone https://github.com/diagramers/diagramers-admin.git
cd diagramers-admin

# Install dependencies
npm install

# Start development server
npm start

# Run tests
npm test

# Build project
npm run build
```

### Code Style
```bash
# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run type-check
```

### Testing
```bash
# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run e2e tests
npm run test:e2e

# Generate coverage report
npm run test:coverage
```

## 📄 License

MIT License - see LICENSE file for details

## 🔗 Related Packages

- [@diagramers/api](./diagramers-api) - Node.js API template
- [@diagramers/cli](./diagramers-cli) - Command-line interface for scaffolding

## 📞 Support

For support and questions:
- Create an issue on GitHub
- Check the documentation
- Review the examples in the codebase
- Join our community discussions

## 🗺️ Roadmap

### Upcoming Features
- [ ] Advanced chart library integration
- [ ] Drag & drop interface builder
- [ ] Advanced form builder
- [ ] Workflow automation
- [ ] Advanced reporting system
- [ ] Multi-language support
- [ ] Advanced theming system
- [ ] Component marketplace
- [ ] Advanced analytics
- [ ] Mobile app companion

### Performance Improvements
- [ ] Virtual scrolling for large datasets
- [ ] Advanced caching strategies
- [ ] Progressive web app features
- [ ] Service worker integration
- [ ] Advanced bundle optimization

### Developer Experience
- [ ] Component storybook
- [ ] Advanced debugging tools
- [ ] Performance monitoring
- [ ] Error tracking integration
- [ ] Advanced testing utilities