@diagramers/admin/SETUP_FEATURE.md

Diagramers Admin Template - React starter for admin dashboards.

# Setup Feature Documentation

## Overview

The Diagramers Admin template now includes a comprehensive setup system that allows developers to configure their project immediately after generation. This feature provides a smooth onboarding experience and ensures that each project is properly branded and configured.

## Features

### 1. Initial Setup Page
- **Automatic Detection**: The app automatically detects if setup is completed
- **Forced Setup**: Users are redirected to setup if not completed
- **Beautiful UI**: Modern, responsive setup interface with gradient background

### 2. Project Configuration
- **Logo Upload**: Drag & drop or click to upload project logo
- **Project Name**: Set custom project name displayed in header and browser tab
- **Theme Selection**: Choose from 10 available color themes (5 light + 5 dark variants)

### 3. Theme Options
Available themes include:
- **Light Blue** - Professional and clean blue theme
- **Dark Blue** - Modern dark blue theme
- **Light Red** - Energetic red theme
- **Dark Red** - Bold dark red theme
- **Light Green** - Fresh green theme
- **Dark Green** - Natural dark green theme
- **Light Purple** - Creative purple theme
- **Dark Purple** - Elegant dark purple theme
- **Light Pink** - Playful pink theme
- **Dark Pink** - Vibrant dark pink theme

### 4. Project Settings Page
After initial setup, users can access a dedicated settings page to:
- **Modify Configuration**: Update logo, project name, and theme
- **Export Configuration**: Download current settings as JSON
- **Import Configuration**: Import settings from JSON file
- **Reset Configuration**: Reset to default and restart setup flow

## Technical Implementation

### Components

#### Setup Page (`/setup`)
- **Location**: `src/views/pages/setup/Setup.js`
- **Purpose**: Initial project configuration
- **Features**: Logo upload, project name, theme selection
- **Styling**: `src/views/pages/setup/Setup.css`

#### Project Settings Page (`/pages/project-settings`)
- **Location**: `src/views/pages/setup/ProjectSettings.js`
- **Purpose**: Ongoing project configuration management
- **Features**: Full CRUD operations for project settings
- **Styling**: `src/views/pages/setup/ProjectSettings.css`

#### Setup Guard
- **Location**: `src/components/setup-guard/SetupGuard.js`
- **Purpose**: Automatic setup detection and routing
- **Behavior**: Redirects to setup if not completed, prevents access to setup if completed

#### Configuration Service
- **Location**: `src/services/configService.js`
- **Purpose**: Centralized configuration management
- **Features**: CRUD operations, import/export, validation

### Routing

The setup system is integrated into the existing routing structure:

```javascript
// Default routes (src/routing/default-routes.js)
{ path: '/setup', exact: true, component: Setup }

// Main routes (src/routes.js)
const pages = {
  setup: lazy(() => import('views/pages/setup/Setup')),
  projectSettings: lazy(() => import('views/pages/setup/ProjectSettings')),
  // ... other pages
};
```

### Data Storage

Configuration is stored in localStorage with the key `projectConfig`:

```javascript
{
  projectName: "My Project",
  defaultTheme: "light-blue",
  logo: "data:image/png;base64,...",
  setupCompleted: true,
  setupDate: "2024-01-01T00:00:00.000Z"
}
```

## Usage

### For Developers

#### 1. Generate New Project
```bash
diagramers admin init my-project
cd my-project
npm start
```

#### 2. Complete Setup
- App automatically redirects to `/setup`
- Upload logo (PNG, JPG, SVG, max 2MB)
- Enter project name
- Select default theme
- Click "Complete Setup"

#### 3. Access Settings Later
- Navigate to `/pages/project-settings`
- Modify any configuration
- Export/import settings as needed

### For End Users

#### Accessing Project Settings
1. Navigate to the admin dashboard
2. Go to Pages → Project Settings
3. Modify configuration as needed
4. Click "Update Settings"

#### Configuration Tools
- **Export**: Download current configuration as JSON
- **Import**: Upload configuration from JSON file
- **Reset**: Clear all settings and restart setup flow

## Customization

### Adding New Themes

1. Add theme constants in `src/constants.js`:
```javascript
export const THEME_COLOR = {
  // ... existing themes
  CustomTheme: 'custom-theme',
};
```

2. Create theme CSS file in `src/sass/themes/_custom-theme.scss`

3. Update theme arrays in Setup and ProjectSettings components

### Modifying Setup Flow

The setup guard can be customized to add additional checks:

```javascript
// In SetupGuard.js
const checkSetupStatus = () => {
  const isSetupCompleted = configService.isSetupCompleted();
  const hasRequiredData = checkRequiredData(); // Custom check
  
  if (!isSetupCompleted || !hasRequiredData) {
    navigate('/setup');
    return;
  }
  // ... rest of logic
};
```

## CLI Integration

The CLI now provides helpful instructions after project generation:

```bash
✅ Admin application 'my-project' initialized successfully!
📁 Project created at: /path/to/my-project
🚀 To start development: cd my-project && npm start
🎨 After starting the app, you'll be redirected to the setup page to configure:
   • Upload your project logo
   • Set your project name
   • Choose your default theme
🔧 You can also access project settings later from the admin panel
```

## Best Practices

### Logo Guidelines
- **Format**: PNG, JPG, or SVG
- **Size**: Maximum 2MB
- **Dimensions**: Recommended 200x200px
- **Background**: Transparent or solid color

### Theme Selection
- Consider your brand colors
- Test both light and dark variants
- Ensure good contrast for accessibility

### Configuration Management
- Export configurations for backup
- Use consistent naming conventions
- Document custom configurations

## Troubleshooting

### Common Issues

#### Setup Page Not Loading
- Check if user is authenticated
- Verify localStorage is available
- Check browser console for errors

#### Logo Upload Fails
- Ensure file is under 2MB
- Check file format (PNG, JPG, SVG)
- Verify browser supports FileReader API

#### Theme Not Applying
- Check if theme CSS is loaded
- Verify theme constant exists
- Clear browser cache

#### Configuration Not Saving
- Check localStorage permissions
- Verify ConfigService is working
- Check for JavaScript errors

### Debug Mode

Enable debug logging by adding to browser console:
```javascript
localStorage.setItem('debug', 'true');
```

## Future Enhancements

### Planned Features
- **API Integration**: Save configuration to backend
- **Multi-tenant Support**: Different configs per tenant
- **Advanced Theming**: Custom color picker
- **Template System**: Pre-built configuration templates
- **Version Control**: Configuration versioning
- **Backup/Restore**: Cloud backup of configurations

### Plugin System
- **Theme Plugins**: Third-party theme support
- **Logo Plugins**: Advanced logo processing
- **Validation Plugins**: Custom validation rules
- **Export Plugins**: Additional export formats

This setup feature provides a comprehensive solution for project configuration and branding, ensuring that every Diagramers admin project starts with proper customization and can be easily maintained throughout its lifecycle.