# Tech Stack & Frameworks

## Project Overview
**Yaltopia Ticket Admin** - Admin dashboard for ticket management system

## Core Technologies

### Frontend Framework
- **React 19.2.0** - Latest version with modern features
  - Component-based architecture
  - Hooks for state management
  - Concurrent rendering
  - Automatic batching

### Language
- **TypeScript 5.9.3** - Type-safe JavaScript
  - Static type checking
  - Enhanced IDE support
  - Better code documentation
  - Reduced runtime errors

### Build Tool
- **Vite 7.2.4** - Next-generation frontend tooling
  - Lightning-fast HMR (Hot Module Replacement)
  - Optimized production builds
  - Native ES modules
  - Plugin ecosystem
  - Code splitting and lazy loading

## UI & Styling

### CSS Framework
- **Tailwind CSS 3.4.17** - Utility-first CSS framework
  - Rapid UI development
  - Consistent design system
  - Responsive design utilities
  - Dark mode support
  - Custom theme configuration

### Component Library
- **Radix UI** - Unstyled, accessible component primitives
  - `@radix-ui/react-avatar` - Avatar component
  - `@radix-ui/react-dialog` - Modal dialogs
  - `@radix-ui/react-dropdown-menu` - Dropdown menus
  - `@radix-ui/react-label` - Form labels
  - `@radix-ui/react-scroll-area` - Custom scrollbars
  - `@radix-ui/react-select` - Select dropdowns
  - `@radix-ui/react-separator` - Visual separators
  - `@radix-ui/react-slot` - Composition utility
  - `@radix-ui/react-switch` - Toggle switches
  - `@radix-ui/react-tabs` - Tab navigation
  - `@radix-ui/react-toast` - Toast notifications

**Why Radix UI?**
- Fully accessible (WCAG compliant)
- Unstyled (full design control)
- Keyboard navigation
- Focus management
- Screen reader support

### UI Utilities
- **class-variance-authority (CVA)** - Component variant management
- **clsx** - Conditional className utility
- **tailwind-merge** - Merge Tailwind classes intelligently
- **tailwindcss-animate** - Animation utilities

### Icons
- **Lucide React 0.561.0** - Beautiful, consistent icon set
  - 1000+ icons
  - Tree-shakeable
  - Customizable size and color
  - Accessible

## Routing

### Router
- **React Router v7.11.0** - Declarative routing
  - Nested routes
  - Protected routes
  - Dynamic routing
  - Navigation guards
  - Location state management

## State Management

### Server State
- **TanStack Query (React Query) 5.90.12** - Powerful data synchronization
  - Automatic caching
  - Background refetching
  - Optimistic updates
  - Pagination support
  - Infinite queries
  - Devtools for debugging

**Why React Query?**
- Eliminates boilerplate for API calls
- Automatic loading/error states
- Smart caching and invalidation
- Reduces global state complexity

### Local State
- **React Hooks** - Built-in state management
  - `useState` - Component state
  - `useEffect` - Side effects
  - `useContext` - Context API
  - Custom hooks for reusability

## Data Fetching

### HTTP Client
- **Axios 1.13.2** - Promise-based HTTP client
  - Request/response interceptors
  - Automatic JSON transformation
  - Request cancellation
  - Progress tracking
  - Error handling
  - TypeScript support

**Features Implemented:**
- Automatic token injection
- Cookie support (`withCredentials`)
- Centralized error handling
- Automatic token refresh
- Request retry logic

## Data Visualization

### Charts
- **Recharts 3.6.0** - Composable charting library
  - Line charts
  - Bar charts
  - Area charts
  - Pie charts
  - Responsive design
  - Customizable styling

**Used For:**
- User growth analytics
- Revenue trends
- API usage statistics
- Error rate monitoring
- Storage analytics

## Utilities

### Date Handling
- **date-fns 4.1.0** - Modern date utility library
  - Lightweight (tree-shakeable)
  - Immutable
  - TypeScript support
  - Timezone support
  - Formatting and parsing

### Notifications
- **Sonner 2.0.7** - Toast notification system
  - Beautiful default styling
  - Promise-based toasts
  - Custom positioning
  - Dismissible
  - Accessible

## Development Tools

### Linting
- **ESLint 9.39.1** - JavaScript/TypeScript linter
  - Code quality enforcement
  - Best practices
  - Error prevention
  - Custom rules

**Plugins:**
- `eslint-plugin-react-hooks` - React Hooks rules
- `eslint-plugin-react-refresh` - Fast Refresh rules
- `typescript-eslint` - TypeScript-specific rules

### Build Tools
- **PostCSS 8.5.6** - CSS transformation
- **Autoprefixer 10.4.23** - Automatic vendor prefixes
- **TypeScript Compiler** - Type checking and transpilation

### Type Definitions
- `@types/node` - Node.js types
- `@types/react` - React types
- `@types/react-dom` - React DOM types

## Architecture Patterns

### Design Patterns Used

1. **Component Composition**
   - Reusable UI components
   - Props-based customization
   - Compound components

2. **Custom Hooks**
   - Reusable logic extraction
   - State management
   - Side effects handling

3. **Higher-Order Components (HOC)**
   - `ProtectedRoute` for authentication
   - Route guards

4. **Render Props**
   - Flexible component APIs
   - Logic sharing

5. **Container/Presentational Pattern**
   - Separation of concerns
   - Logic vs UI separation

6. **API Client Pattern**
   - Centralized API calls
   - Consistent error handling
   - Interceptor-based auth

## Project Structure

```
yaltopia-ticket-admin/
├── src/
│   ├── app/                    # App configuration
│   │   └── query-client.ts     # React Query setup
│   ├── assets/                 # Static assets
│   ├── components/             # Reusable components
│   │   ├── ui/                 # Radix UI components
│   │   ├── ErrorBoundary.tsx   # Error handling
│   │   └── ProtectedRoute.tsx  # Auth guard
│   ├── layouts/                # Layout components
│   │   └── app-shell.tsx       # Main layout
│   ├── lib/                    # Utilities
│   │   ├── api-client.ts       # Axios configuration
│   │   └── utils.ts            # Helper functions
│   ├── pages/                  # Page components
│   │   ├── admin/              # Admin pages
│   │   ├── login/              # Login page
│   │   └── ...
│   ├── App.tsx                 # Root component
│   ├── main.tsx                # Entry point
│   └── index.css               # Global styles
├── public/                     # Public assets
├── dev-docs/                   # Documentation
├── .env.example                # Environment template
├── vite.config.ts              # Vite configuration
├── tailwind.config.js          # Tailwind configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies

```

## Performance Optimizations

### Code Splitting
- **Manual Chunks** - Vendor code separation
  - `react-vendor` - React core libraries
  - `ui-vendor` - Radix UI components
  - `chart-vendor` - Recharts library
  - `query-vendor` - TanStack Query

### Build Optimizations
- Tree shaking (unused code removal)
- Minification
- Compression
- Source map generation (disabled in production)
- Chunk size optimization (1000kb limit)

### Runtime Optimizations
- React Query caching
- Lazy loading routes
- Image optimization
- Debounced search inputs
- Memoization where needed

## Browser Support

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

**Minimum Versions:**
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Development Environment

### Requirements
- **Node.js**: 18+ (LTS recommended)
- **npm**: 9+ or **yarn**: 1.22+
- **Git**: 2.0+

### Recommended IDE
- **VS Code** with extensions:
  - ESLint
  - Prettier
  - Tailwind CSS IntelliSense
  - TypeScript and JavaScript Language Features
  - Auto Rename Tag
  - Path Intellisense

### Development Server
- **Port**: 5173 (configurable)
- **Hot Module Replacement**: Enabled
- **Host**: 0.0.0.0 (accessible from network)

## Deployment Options

### Static Hosting
- **Netlify** - Recommended
- **Vercel** - Recommended
- **AWS S3 + CloudFront**
- **Azure Static Web Apps**
- **GitHub Pages**

### Container Deployment
- **Docker** - Nginx-based container
- **Kubernetes** - Scalable deployment
- **AWS ECS/Fargate**
- **Google Cloud Run**

### CDN
- **CloudFlare** - Recommended for caching and security
- **AWS CloudFront**
- **Fastly**

## Monitoring & Analytics (Optional)

### Error Tracking
- **Sentry** - Error monitoring
- **LogRocket** - Session replay
- **Rollbar** - Error tracking

### Analytics
- **Google Analytics 4**
- **Mixpanel** - Product analytics
- **Amplitude** - User behavior

### Performance Monitoring
- **Lighthouse** - Performance audits
- **Web Vitals** - Core metrics
- **New Relic** - APM

## Security Tools

### Dependency Scanning
- `npm audit` - Vulnerability scanning
- **Snyk** - Continuous security monitoring
- **Dependabot** - Automated updates

### Code Quality
- **SonarQube** - Code quality and security
- **CodeQL** - Security analysis

## Testing (Not Yet Implemented)

### Recommended Testing Stack
- **Vitest** - Unit testing (Vite-native)
- **React Testing Library** - Component testing
- **Playwright** - E2E testing
- **MSW** - API mocking

## Comparison with Alternatives

### Why React over Vue/Angular?
- Larger ecosystem
- Better TypeScript support
- More job opportunities
- Flexible architecture
- Strong community

### Why Vite over Webpack/CRA?
- 10-100x faster HMR
- Faster cold starts
- Better developer experience
- Modern ES modules
- Smaller bundle sizes

### Why Tailwind over CSS-in-JS?
- Better performance (no runtime)
- Smaller bundle size
- Easier to maintain
- Better IDE support
- Consistent design system

### Why React Query over Redux?
- Less boilerplate
- Automatic caching
- Better for server state
- Simpler API
- Built-in loading/error states

## Version History

| Package | Current | Latest Stable | Notes |
|---------|---------|---------------|-------|
| React | 19.2.0 | 19.2.0 | ✅ Latest |
| TypeScript | 5.9.3 | 5.9.x | ✅ Latest |
| Vite | 7.2.4 | 7.x | ✅ Latest |
| React Router | 7.11.0 | 7.x | ✅ Latest |
| TanStack Query | 5.90.12 | 5.x | ✅ Latest |
| Tailwind CSS | 3.4.17 | 3.x | ✅ Latest |

## Future Considerations

### Potential Additions
- **React Hook Form** - Form management
- **Zod** - Schema validation
- **Zustand** - Lightweight state management
- **Framer Motion** - Advanced animations
- **i18next** - Internationalization
- **React Helmet** - SEO management

### Potential Upgrades
- **React 19 Features** - Use new concurrent features
- **Vite 6** - When stable
- **TypeScript 5.10** - When released

## Resources

### Documentation
- [React Docs](https://react.dev)
- [TypeScript Docs](https://www.typescriptlang.org/docs)
- [Vite Docs](https://vitejs.dev)
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
- [React Router Docs](https://reactrouter.com)
- [TanStack Query Docs](https://tanstack.com/query)
- [Radix UI Docs](https://www.radix-ui.com)

### Learning Resources
- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app)
- [Tailwind CSS Best Practices](https://tailwindcss.com/docs/reusing-styles)
- [React Query Tutorial](https://tanstack.com/query/latest/docs/framework/react/overview)

## License
Proprietary - All rights reserved