Yaltopia-Ticket-Admin/dev-docs/QUICK_REFERENCE.md

# Quick Reference Guide

## Common Commands

```bash
# Development
npm run dev                 # Start dev server (http://localhost:5173)
npm run build              # Build for production
npm run build:prod         # Build with production env
npm run preview            # Preview production build
npm run lint               # Run ESLint
npm run lint:fix           # Fix ESLint errors
npm run type-check         # TypeScript type checking

# Deployment
vercel --prod              # Deploy to Vercel
netlify deploy --prod      # Deploy to Netlify
docker build -t app .      # Build Docker image
docker run -p 80:80 app    # Run Docker container
```

## Environment Variables

```env
# Required
VITE_API_URL=http://localhost:3000/api/v1

# Optional
VITE_ENV=development
VITE_ANALYTICS_ID=
VITE_SENTRY_DSN=
```

## File Structure

```
├── src/
│   ├── app/              # App config (query client)
│   ├── components/       # Reusable components
│   │   └── ui/          # UI components
│   ├── layouts/          # Layout components
│   ├── lib/              # Utils & API client
│   ├── pages/            # Page components
│   │   └── admin/       # Admin pages
│   ├── App.tsx          # Main app
│   └── main.tsx         # Entry point
├── .env.example          # Env template
├── vite.config.ts        # Vite config
├── package.json          # Dependencies
└── README.md            # Documentation
```

## Key Files

| File | Purpose |
|------|---------|
| `src/lib/api-client.ts` | API configuration & helpers |
| `src/app/query-client.ts` | React Query setup |
| `src/components/ErrorBoundary.tsx` | Error handling |
| `vite.config.ts` | Build configuration |
| `.env.example` | Environment template |

## API Client Usage

```typescript
import { adminApiHelpers } from '@/lib/api-client';

// Get users
const response = await adminApiHelpers.getUsers({ page: 1, limit: 20 });

// Get user by ID
const user = await adminApiHelpers.getUser(userId);

// Update user
await adminApiHelpers.updateUser(userId, { isActive: false });

// Delete user
await adminApiHelpers.deleteUser(userId);
```

## React Query Usage

```typescript
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// Fetch data
const { data, isLoading, error } = useQuery({
  queryKey: ['users', page],
  queryFn: async () => {
    const response = await adminApiHelpers.getUsers({ page });
    return response.data;
  },
});

// Mutate data
const mutation = useMutation({
  mutationFn: async (data) => {
    await adminApiHelpers.updateUser(id, data);
  },
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['users'] });
  },
});
```

## Routing

```typescript
import { useNavigate, useParams } from 'react-router-dom';

// Navigate
const navigate = useNavigate();
navigate('/admin/users');

// Get params
const { id } = useParams();
```

## Toast Notifications

```typescript
import { toast } from 'sonner';

toast.success('Success message');
toast.error('Error message');
toast.info('Info message');
toast.warning('Warning message');
```

## Deployment Quick Start

### Vercel
```bash
npm i -g vercel
vercel login
vercel --prod
```

### Netlify
```bash
npm i -g netlify-cli
netlify login
netlify deploy --prod
```

### Docker
```bash
docker build -t yaltopia-admin .
docker run -p 80:80 yaltopia-admin
```

## Troubleshooting

### Build fails
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
```

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

### Blank page after deploy
- Check browser console
- Verify API URL in env vars
- Check server config for SPA routing

### API calls failing
- Check CORS on backend
- Verify API URL
- Check network tab in DevTools

## Security Checklist

- [ ] HTTPS enabled
- [ ] Environment variables set
- [ ] CORS configured
- [ ] Security headers added
- [ ] Error tracking set up
- [ ] Monitoring configured

## Performance Tips

- Use code splitting for large routes
- Lazy load heavy components
- Optimize images
- Enable compression (gzip/brotli)
- Use CDN for static assets

## Useful Links

- [React Query Docs](https://tanstack.com/query/latest)
- [React Router Docs](https://reactrouter.com/)
- [Vite Docs](https://vitejs.dev/)
- [Tailwind CSS Docs](https://tailwindcss.com/)
- [Radix UI Docs](https://www.radix-ui.com/)

## Support

- Check `README.md` for detailed docs
- See `DEPLOYMENT.md` for deployment guide
- Review `SECURITY.md` for security best practices
- Read `PRODUCTION_READY_SUMMARY.md` for status