# 🚀 Setup & Run Instructions

## Step-by-Step Setup

### 1️⃣ Prerequisites
Make sure you have installed:
- **Node.js** v16+ ([Download](https://nodejs.org/))
- **npm** v7+ (comes with Node.js)
- **Git** (optional)

Verify installation:
```bash
node --version
npm --version
```

### 2️⃣ Navigate to Project Directory
```bash
cd /var/www/html/worldnumerology/master_program_new_latest_working/master_reportadmin/frontend/numerology-cms-frontend
```

### 3️⃣ Install Dependencies
```bash
npm install
```

This will install all required packages:
- React & React DOM
- React Router DOM
- Axios
- Tailwind CSS
- React Icons
- Sonner (Toast notifications)
- Vite (Build tool)

**Install time:** 2-5 minutes depending on your internet

### 4️⃣ Configure Environment

Create `.env.local` file:
```bash
cp .env.example .env.local
```

Edit `.env.local`:
```env
VITE_API_URL=http://localhost:3000/api
```

Replace with your actual backend API URL.

### 5️⃣ Start Development Server
```bash
npm run dev
```

**Output:**
```
➜  local:   http://localhost:5173/
➜  press h to show help
```

### 6️⃣ Open in Browser
Click or paste: `http://localhost:5173`

The app will open automatically (or manually open the URL)

## 🔐 Demo Login

**Credentials (Pre-filled):**
- Email: `admin@example.com`
- Password: `admin123`

Click the login button or "Use Demo Credentials" button

## ✅ Verify Installation

After starting the dev server:

1. ✅ App loads at `http://localhost:5173`
2. ✅ Can see login page
3. ✅ Demo credentials work
4. ✅ Can navigate to Dashboard
5. ✅ Can see Users page
6. ✅ Dark mode toggle works
7. ✅ Toast notifications appear

## 📦 Build for Production

When ready to deploy:

```bash
npm run build
```

**Output:** Creates `dist/` folder with optimized build

Preview the build locally:
```bash
npm run preview
```

## 🐛 Troubleshooting

### Port Already in Use
If port 5173 is busy:
```bash
npm run dev -- --port 3000
```

### Dependencies Not Installing
```bash
rm -rf node_modules package-lock.json
npm install
```

### CORS Error
Update `VITE_API_URL` in `.env.local` to match your backend

### Dark Mode Not Working
Clear localStorage:
```bash
localStorage.clear()
```
Then refresh the page

### Blank Page
1. Open DevTools (F12)
2. Check Console for errors
3. Check Network tab for API calls
4. Ensure backend is running

## 📁 Project Structure Summary

```
numerology-cms-frontend/
├── src/
│   ├── api/              # API configuration & endpoints
│   ├── components/       # Reusable components
│   ├── context/          # State management (Auth, Theme)
│   ├── pages/            # Page components
│   ├── utils/            # Helpers, hooks, notifications
│   ├── App.jsx           # Main app component
│   ├── main.jsx          # Entry point
│   └── index.css         # Tailwind directives
├── index.html            # HTML template
├── package.json          # Dependencies
├── vite.config.js        # Vite configuration
├── tailwind.config.js    # Tailwind configuration
├── postcss.config.js     # PostCSS configuration
└── README.md             # Full documentation
```

## 🔧 Configuration Files

### vite.config.js
- Development server settings
- Port configuration
- Plugins setup

### tailwind.config.js
- Color theme
- Custom shadows (glass effect)
- Dark mode configuration

### postcss.config.js
- Tailwind CSS processing
- Autoprefixer for browser compatibility

## 🚀 Quick Commands Reference

```bash
# Development
npm run dev              # Start dev server at localhost:5173

# Production
npm run build            # Build optimized version
npm run preview          # Preview production build

# Code Quality
npm run lint             # Run ESLint checker

# Cleanup
npm install              # Install dependencies
npm cache clean --force  # Clear npm cache
```

## 📝 First Steps After Setup

1. **Login** with demo credentials
2. **Explore Dashboard** - View stats cards
3. **Go to Users Page** - See table with pagination
4. **Add User** - Click "Add User" button
5. **Edit User** - Click pencil icon
6. **Delete User** - Click trash icon (superadmin only)
7. **Search Users** - Use search input (auto-debounced)
8. **Toggle Dark Mode** - Click moon/sun in sidebar
9. **Check Console** - F12 to see API requests

## 🎨 Customization

### Change API URL
Edit `.env.local`:
```env
VITE_API_URL=https://your-api.com/api
```

### Change Colors
Edit `tailwind.config.js`:
```js
colors: {
  indigo: {...},      // Primary color
  purple: {...},      // Secondary color
}
```

### Change Port
```bash
npm run dev -- --port 8080
```

## 🔗 API Integration

The app expects these endpoints from your backend:

### Authentication
```
POST /auth/login
POST /auth/register
POST /auth/refresh
POST /auth/logout
```

### Users
```
GET /users?page=1&limit=10&search=
GET /users/:id
POST /users
PUT /users/:id
PATCH /users/:id/soft-delete
```

See [README.md](./README.md#-api-endpoints) for full details.

## 🎓 Learning Resources

- [React Documentation](https://react.dev/)
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
- [React Router Docs](https://reactrouter.com/)
- [Axios Docs](https://axios-http.com/)
- [Vite Docs](https://vitejs.dev/)

## ✨ Next Steps

1. ✅ Complete setup (you are here)
2. 🔨 Customize components to your needs
3. 🎨 Update colors and branding
4. 🔌 Connect to your backend API
5. 📱 Test on mobile devices
6. 🚀 Deploy to production

## 📞 Getting Help

If you encounter issues:

1. Check the [README.md](./README.md#-troubleshooting)
2. Review browser console (F12)
3. Check Network tab for API errors
4. Verify backend is running
5. Check `.env.local` configuration

## 🎉 You're Ready!

Your premium CMS dashboard is now set up and running. Enjoy building! 

For questions or feedback, refer to the documentation or create an issue.

**Happy coding! 🚀**
