AyposWeb/.github/copilot-instructions.md

Copilot Instructions for AyposWeb

Project Overview

AyposWeb is a React-based monitoring system for virtual machine infrastructure with real-time data visualization. It provides VM migration advice, environmental monitoring, stress testing, and preventive maintenance features through a Material-UI interface.

Tech Stack & Architecture

• Frontend: React 18 + TypeScript + Vite
• UI Framework: Material-UI (MUI) v5 with custom B'GREEN branding
• Charts: Multiple libraries (Plotly.js, Recharts, Chart.js, MUI X-Charts)
• Routing: React Router v6 with declarative routes in App.tsx
• State: React hooks with custom polling patterns (no external state management)
• Build: Vite with standard TypeScript config
• Deployment: Docker + nginx or Vercel with API proxy

Core Architecture Patterns

Service Layer Pattern

Services use singleton pattern with axios HTTP client:

// All services follow this pattern in src/services/
class ServiceName {
  private static instance: ServiceName;
  public static getInstance(): ServiceName { /* singleton */ }
}

Smart Polling Hook Pattern

Custom hooks in src/components/Migration/hooks.ts implement adaptive polling:

• Starts with fast intervals (5s) when data changes
• Gradually increases to slower intervals (30s) when stable
• Always use useSmartPolling for real-time data fetching

Environment Configuration

// src/config/env.ts handles dev/prod API routing
const getApiUrl = (): string => {
  if (import.meta.env.PROD) return '/api'; // Vercel proxy
  return import.meta.env.VITE_API_URL || 'fallback-url';
};

Component Organization

Layout Structure

• MainLayout provides responsive sidebar with mobile menu toggle
• Sidebar uses custom styled MUI components with B'GREEN theming
• Pages in src/pages/ are route components that compose feature components

Material-UI Customization

// src/theme.ts defines B'GREEN brand colors
primary: { main: '#028a4a' } // B'GREEN green

• Use styled() for component-specific styling
• Custom StyledListItemButton pattern for navigation
• Responsive breakpoints with useMediaQuery(theme.breakpoints.down('md'))

Chart Component Patterns

Multiple charting libraries used for different purposes:

• Plotly.js: Complex scientific visualizations in migration analysis
• Recharts: Simple bar/line charts for resource distribution
• MUI X-Charts: Native MUI integration for basic charts
• Chart.js: Time-series data with date-fns adapter

Data Flow Patterns

API Integration

// Services handle all external API calls
const response = await axios.post(`${BASE_URL}/endpoint`, data, {
  headers: { 'Content-Type': 'application/json' }
});

Type Safety

• Strict TypeScript with comprehensive interfaces in src/types/
• Migration-specific types in src/components/Migration/types.ts
• Monitoring types shared across services in src/types/monitoring.ts

Error Handling

• Services log requests for debugging: console.log('Starting operation with config:', config)
• Use try/catch with proper error propagation to UI components

Development Workflows

Build Commands

npm run dev          # Vite dev server on :5173
npm run build        # TypeScript compilation + Vite build
npm run preview      # Preview production build

Environment Setup

• Development: Uses VITE_API_URL environment variable
• Production: API calls routed through /api proxy (see vercel.json)
• No .env.example - check README for environment variables

Key Files to Understand

• src/App.tsx: Route definitions and global providers
• src/components/Layout/MainLayout.tsx: Responsive layout logic
• src/services/monitoringService.ts: Main API service patterns
• src/components/Migration/hooks.ts: Custom polling and data fetching
• src/theme.ts: B'GREEN brand implementation

Project-Specific Conventions

Import Organization

1. React/third-party imports
2. MUI component imports
3. Local component imports
4. Service/utility imports
5. Asset imports (images/icons)

Component Naming

• Page components: PascalCase in src/pages/
• Feature components: PascalCase in feature folders under src/components/
• Service files: camelCase with "Service" suffix

Styling Approach

• Use MUI's styled() over CSS-in-JS or external CSS
• Custom styled components follow Styled{ComponentName} naming
• Responsive design with MUI breakpoint system
• B'GREEN brand colors defined in theme, not hardcoded

When adding new features, follow the established service layer pattern, use TypeScript interfaces for all data structures, and implement smart polling for real-time data when appropriate.