forked from BLC/AyposWeb
125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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:
|
|
```typescript
|
|
// 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
|
|
```typescript
|
|
// 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
|
|
```typescript
|
|
// 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
|
|
```typescript
|
|
// 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
|
|
```bash
|
|
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. |