Tempering-Machine-Control-System/python_rewrite/frontend/README.md

# Chocolate Tempering Machine - Frontend

A modern React TypeScript frontend for the industrial chocolate tempering machine control system. Designed for touch-friendly operation on industrial tablets with real-time monitoring capabilities.

## Features

- **Touch-Optimized Interface**: Designed for industrial tablets with large buttons and touch-friendly interactions
- **Real-time Monitoring**: WebSocket-based live updates of temperature, process status, and system health
- **Responsive Design**: Works on desktop, tablet, and mobile devices
- **Industrial Theme**: Professional interface suitable for industrial environments
- **Process Control**: Start, pause, resume, and monitor tempering processes
- **Recipe Management**: Create, edit, and manage chocolate tempering recipes
- **Hardware Monitoring**: Real-time status of temperature sensors, motors, and communication
- **Safety Alerts**: Visual and audio alerts for safety conditions and alarms
- **User Management**: Role-based access control with operator, supervisor, and admin roles
- **Data Visualization**: Temperature charts and process analytics

## Technology Stack

- **React 18** - Modern React with hooks and concurrent features
- **TypeScript** - Type-safe development
- **Vite** - Fast build tool and development server
- **Tailwind CSS** - Utility-first CSS framework for rapid styling
- **React Router** - Client-side routing
- **Zustand** - Lightweight state management
- **React Query** - Server state management and caching
- **Socket.IO Client** - Real-time WebSocket communication
- **Recharts** - Charts and data visualization
- **Lucide React** - Modern icon library
- **React Hook Form** - Form management
- **React Hot Toast** - Toast notifications

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Running backend API server (see `../` for Python backend)

### Installation

```bash
# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start development server
npm run dev
```

The application will be available at `http://localhost:3000`

### Build for Production

```bash
# Build for production
npm run build

# Preview production build
npm run preview
```

## Project Structure

```
src/
├── components/           # Reusable UI components
│   ├── common/          # Generic components (buttons, modals, etc.)
│   ├── layout/          # Layout components (header, sidebar, etc.)
│   ├── process/         # Process control components
│   ├── recipe/          # Recipe management components
│   └── charts/          # Data visualization components
├── pages/               # Page components
│   ├── Dashboard.tsx    # Main dashboard
│   ├── ProcessControl.tsx
│   ├── RecipeManagement.tsx
│   ├── HardwareStatus.tsx
│   ├── SystemSettings.tsx
│   └── UserManagement.tsx
├── hooks/               # Custom React hooks
│   ├── useWebSocket.ts  # WebSocket connection management
│   ├── useApi.ts        # API data fetching
│   └── useLocalStorage.ts
├── stores/              # Zustand state stores
│   ├── systemStore.ts   # System status and configuration
│   ├── processStore.ts  # Process state management
│   └── userStore.ts     # User authentication and preferences
├── services/            # External service integrations
│   ├── api.ts           # REST API client
│   ├── websocket.ts     # WebSocket service
│   └── auth.ts          # Authentication service
├── types/               # TypeScript type definitions
│   └── index.ts         # All type definitions
├── utils/               # Utility functions
│   ├── formatting.ts    # Data formatting helpers
│   ├── validation.ts    # Form validation
│   └── constants.ts     # Application constants
└── styles/              # Global styles and themes
    └── index.css        # Tailwind CSS and custom styles
```

## Key Components

### Dashboard
- System overview with status cards
- Real-time temperature displays
- Process monitoring
- Quick action buttons
- Hardware status indicators

### Process Control
- Recipe selection and start controls
- Live temperature monitoring with charts
- Process phase indicators
- Emergency stop functionality
- Process history and logs

### Recipe Management
- Recipe CRUD operations
- Temperature profile visualization
- Recipe validation and testing
- Import/export capabilities

### Hardware Status
- Modbus communication status
- Temperature sensor readings
- Motor status and control
- Diagnostic information

### Safety Monitoring
- Active alarm display
- Safety system status
- Alarm acknowledgment
- Emergency procedures

## Configuration

### Environment Variables

Create a `.env` file with the following variables:

```env
VITE_API_BASE_URL=http://localhost:8000
VITE_WEBSOCKET_URL=ws://localhost:8000
VITE_APP_TITLE=Tempering Control System
VITE_APP_ENV=development
```

### API Integration

The frontend communicates with the Python backend through:

- **REST API**: HTTP requests for CRUD operations
- **WebSocket**: Real-time updates for live data
- **Authentication**: JWT token-based authentication

### Touch Optimization

The interface is optimized for industrial tablets:

- Minimum touch target size of 44px
- Large, clearly labeled buttons
- High contrast colors for visibility
- Disabled text selection and zoom
- Touch-friendly gestures

## Development

### Code Style

The project uses:

- **ESLint** - Code linting
- **Prettier** - Code formatting
- **TypeScript strict mode** - Type checking
- **Tailwind CSS classes** - Consistent styling

### State Management

- **Zustand** for global application state
- **React Query** for server state caching
- **React hooks** for local component state

### Real-time Updates

WebSocket connection provides:

- Process status updates every 1-2 seconds
- Temperature readings every 5 seconds
- Immediate safety alerts
- System health monitoring

## Deployment

### Docker Deployment

The frontend can be containerized and deployed with Docker:

```dockerfile
FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### Production Considerations

- Enable HTTPS for secure communication
- Configure proper CORS settings
- Set up monitoring and error tracking
- Implement proper caching strategies
- Configure WebSocket proxy in production

## Browser Support

- Chrome 90+ (recommended for industrial use)
- Firefox 88+
- Safari 14+
- Edge 90+

Chrome is recommended for industrial environments due to its excellent WebSocket support and performance on touch devices.

## Troubleshooting

### Common Issues

1. **WebSocket Connection Failed**
   - Check backend server is running
   - Verify WebSocket URL in environment variables
   - Check firewall settings

2. **API Requests Failing**
   - Verify API base URL configuration
   - Check backend server health endpoint
   - Review CORS settings

3. **Touch Interface Issues**
   - Ensure proper viewport meta tag
   - Check touch-action CSS properties
   - Verify button minimum sizes

### Development Tips

- Use React DevTools for component debugging
- Enable WebSocket debugging in browser DevTools
- Use Zustand DevTools for state management debugging
- Check Network tab for API request issues

## License

This project is part of the chocolate tempering machine control system. See the main project license for details.