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

### Docker Deployment (Recommended)

1. Build the Docker image:
```bash
docker build -t yaltopia-admin:latest .
```

2. Run the container:
```bash
docker run -p 8080:80 yaltopia-admin:latest
```

3. Deploy to your cloud provider (AWS, GCP, Azure, DigitalOcean, etc.)

### Traditional VPS Deployment

1. Build the application: `npm run build:prod`
2. Copy the `dist` directory to your web server
3. Configure nginx or Apache to serve the static files
4. Set up redirects for SPA routing (see nginx.conf example)

### SPA Routing Configuration

For proper routing with nginx, use the included `nginx.conf` file or add this configuration:

```nginx
location / {
  try_files $uri $uri/ /index.html;
}
```
The project includes a `Dockerfile` and `nginx.conf` for containerized deployment.

See [DEPLOYMENT.md](dev-docs/DEPLOYMENT.md) for detailed deployment instructions.

    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