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

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
• TypeScript Docs
• Vite Docs
• Tailwind CSS Docs
• React Router Docs
• TanStack Query Docs
• Radix UI Docs

Learning Resources

• React TypeScript Cheatsheet
• Tailwind CSS Best Practices
• React Query Tutorial

License

Proprietary - All rights reserved