@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)

# 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

# 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

# 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

# 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

# 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

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

🔧 Configuration

Environment Variables

# 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

// 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

// 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

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

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

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

import { Navigation, Menu, Breadcrumb } from '@diagramers/admin';

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

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

🔐 Authentication

Login Component

import { LoginForm } from '@diagramers/admin';

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

Protected Routes

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

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

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

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

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

// 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

// 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

// 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

// 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

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

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

// 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

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

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: '[email protected]' },
  });
  
  fireEvent.change(screen.getByLabelText('Password'), {
    target: { value: 'password123' },
  });
  
  fireEvent.click(screen.getByRole('button', { name: /login/i }));
  
  expect(mockOnLogin).toHaveBeenCalledWith({
    email: '[email protected]',
    password: 'password123',
  });
});

Integration Testing

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: '[email protected]' },
    { id: 2, name: 'Jane Smith', email: '[email protected]' },
  ];
  
  render(<DataTable data={mockData} />);
  
  await waitFor(() => {
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('Jane Smith')).toBeInTheDocument();
  });
});

🚀 Deployment

Build Configuration

// 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

# 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
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

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

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

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

// 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

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

import { sanitizeHtml } from '@diagramers/admin';

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

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

📚 Documentation

Component Documentation

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

API Documentation

/**
 * @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

# 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

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run type-check

Testing

# 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 - Node.js API template
• @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