Yaltopia-Ticket-Admin/README.md

# Yaltopia Ticket Admin

Admin dashboard for Yaltopia Ticket management system built with React, TypeScript, and Vite.

> 📚 **For detailed documentation, see [dev-docs/](./dev-docs/README.md)**

## Features

- User Management
- Analytics Dashboard
- Security Monitoring
- System Health Monitoring
- Audit Logs
- Announcements Management
- Maintenance Mode
- API Key Management

## Tech Stack

- React 19
- TypeScript
- Vite
- TanStack Query (React Query)
- React Router v7
- Tailwind CSS
- Radix UI Components
- Recharts for data visualization
- Axios for API calls

## Prerequisites

- Node.js 18+ 
- npm or yarn

## Getting Started

### 1. Clone the repository

```bash
git clone <repository-url>
cd yaltopia-ticket-admin
```

### 2. Install dependencies

```bash
npm install
```

### 3. Environment Configuration

Copy the example environment file and configure it:

```bash
cp .env.example .env
```

Edit `.env` and set your API URL:

```env
VITE_BACKEND_API_URL=http://localhost:3000/api/v1
VITE_ENV=development
```

### 4. Run development server

```bash
npm run dev
```

The application will be available at `http://localhost:5173`

## Building for Production

### 1. Configure production environment

Copy the production environment example:

```bash
cp .env.production.example .env.production
```

Edit `.env.production` with your production API URL:

```env
VITE_BACKEND_API_URL=https://api.yourdomain.com/api/v1
VITE_ENV=production
```

### 2. Build the application

```bash
npm run build:prod
```

The production build will be in the `dist` directory.

### 3. Preview production build locally

```bash
npm run preview
```

## Deployment

### Static Hosting (Netlify, Vercel, etc.)

1. Build the application: `npm run build:prod`
2. Deploy the `dist` directory
3. Configure environment variables in your hosting platform
4. Set up redirects for SPA routing (see below)

### SPA Routing Configuration

For proper routing, add a redirect rule:

**Netlify** (`netlify.toml`):
```toml
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```

**Vercel** (`vercel.json`):
```json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
```

### Docker Deployment

Create a `Dockerfile`:

```dockerfile
FROM node:18-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build:prod

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

Create `nginx.conf`:

```nginx
server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}
```

Build and run:

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

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `VITE_BACKEND_API_URL` | Backend API base URL | Yes | `http://localhost:3000/api/v1` |
| `VITE_ENV` | Environment name | No | `development` |
| `VITE_ANALYTICS_ID` | Analytics tracking ID | No | - |
| `VITE_SENTRY_DSN` | Sentry error tracking DSN | No | - |

## Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run build:prod` - Build with production environment
- `npm run preview` - Preview production build
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Fix ESLint errors
- `npm run type-check` - Run TypeScript type checking

## Project Structure

```
src/
├── app/              # App configuration (query client)
├── assets/           # Static assets
├── components/       # Reusable UI components
│   └── ui/          # Shadcn UI components
├── layouts/          # Layout components
├── lib/              # Utilities and API client
├── pages/            # Page components
│   ├── admin/       # Admin pages
│   ├── dashboard/   # Dashboard pages
│   └── ...
├── App.tsx          # Main app component
├── main.tsx         # App entry point
└── index.css        # Global styles
```

## Security Considerations

### Current Implementation

- JWT tokens stored in localStorage
- Token automatically attached to API requests
- Automatic redirect to login on 401 errors
- Error handling for common HTTP status codes

### Production Recommendations

1. **Use httpOnly cookies** instead of localStorage for tokens
2. **Implement HTTPS** - Never deploy without SSL/TLS
3. **Add security headers** - CSP, HSTS, X-Frame-Options
4. **Enable CORS** properly on your backend
5. **Implement rate limiting** on authentication endpoints
6. **Add error boundary** for graceful error handling
7. **Set up monitoring** (Sentry, LogRocket, etc.)
8. **Regular security audits** - Run `npm audit` regularly

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

1. Create a feature branch
2. Make your changes
3. Run linting and type checking
4. Submit a pull request

## License

Proprietary - All rights reserved