234 lines
5.1 KiB
Markdown
234 lines
5.1 KiB
Markdown
# 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
|
|
|