Tempering-Machine-Control-System/docs/01-system-overview.md

# System Overview - Chocolate Tempering Machine Control System

## Executive Summary

This is an industrial chocolate tempering machine control system that manages the precise heating, cooling, and pouring processes required for chocolate tempering. The system runs on a single-board computer with a touch interface and communicates with hardware via Modbus RTU over serial communication.

## High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    AVALONIA UI LAYER                        │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────────────┐ │
│  │    Home     │ │  Settings   │ │      Diagnostics       │ │
│  │   Screen    │ │   Screen    │ │       Screen           │ │
│  └─────────────┘ └─────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│                  CONTROL LOGIC LAYER                       │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐  │
│  │   Recipe     │ │    Motor     │ │    Temperature      │  │
│  │  Manager     │ │  Controller  │ │    Controller       │  │
│  └──────────────┘ └──────────────┘ └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│               COMMUNICATION LAYER                           │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐  │
│  │   Modbus     │ │    Serial    │ │      Queue          │  │
│  │   Master     │ │    Port      │ │    Manager          │  │
│  └──────────────┘ └──────────────┘ └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│                  HARDWARE LAYER                             │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐  │
│  │ Temperature  │ │    Motors    │ │       I/O           │  │
│  │   Sensors    │ │  & Pumps     │ │    Controls         │  │
│  └──────────────┘ └──────────────┘ └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## System Components

### 1. User Interface Layer
- **Technology**: Avalonia UI (.NET 8)
- **Purpose**: Touch-based operator interface
- **Key Features**:
  - Recipe selection and management
  - Real-time temperature monitoring
  - Motor control and status
  - Error display and diagnostics
  - Auto-dimming and power management

### 2. Control Logic Layer
- **Architecture**: Multi-threaded event-driven system
- **Key Components**:
  - Recipe execution engine
  - Temperature control system
  - Motor coordination logic
  - Safety and error handling

### 3. Communication Layer
- **Protocol**: Modbus RTU over RS-485
- **Features**:
  - Queue-based message handling
  - Automatic retry with exponential backoff
  - CRC validation
  - Timeout management

### 4. Data Persistence Layer
- **Technology**: CSV files
- **Storage**:
  - Recipe definitions
  - Machine configuration
  - Hardware mapping
  - PID parameters

## Threading Model

```
MainWindow Process
├── MonitorPortsLoop Thread (Priority: Highest)
│   ├── Hardware Communication
│   ├── Recipe Phase Management
│   ├── Temperature Monitoring
│   └── Motor Control
├── ScreenLoop Thread
│   ├── Error Handling
│   ├── UI State Management
│   └── Button Enable/Disable Logic
├── InteractiveUILoop Thread
│   ├── Visual Feedback
│   └── Status Indicators
├── TouchLoop Thread
│   ├── Activity Tracking
│   └── Screen Dimming
├── CheckInternetLoop Thread
│   └── Network Connectivity
└── SerialThreadLoop Thread
    ├── Queue Management
    ├── Message Retry Logic
    └── Communication Timing
```

## Key Business Processes

### 1. Chocolate Tempering Process
The system follows a precise three-phase tempering process:

```
Pre-heating → Heating → Cooling → Pouring → Complete
    │           │         │         │
    ▼           ▼         ▼         ▼
 Warm up    Reach goal  Cool to   Maintain
 hardware   temperature  precise   pouring
 to working              temp     temperature
 temperature
```

### 2. Motor Coordination
Multiple motors must be coordinated for proper operation:
- **Mixer Motor**: Tank agitation
- **Fountain Motor**: Chocolate circulation
- **Pump Motors**: Fluid transfer
- **Vibrator**: Mold preparation
- **Compressor**: Cooling system

### 3. Safety Systems
- Real-time error monitoring
- Automatic motor shutoff on errors
- Temperature limit enforcement
- Communication timeout handling
- Grid power monitoring

## Deployment Architecture

```
┌─────────────────────────────────────────┐
│         Single Board Computer           │
│  ┌─────────────────────────────────────┐│
│  │       Linux Operating System        ││
│  │  ┌─────────────────────────────────┐││
│  │  │      .NET 8 Runtime             │││
│  │  │  ┌─────────────────────────────┐│││
│  │  │  │   Avalonia Application      ││││
│  │  │  └─────────────────────────────┘│││
│  │  └─────────────────────────────────┘││
│  └─────────────────────────────────────┘│
│                    │                    │
│              Serial Port                │
└─────────────────────────────────────────┘
                     │
              RS-485 Interface
                     │
┌─────────────────────────────────────────┐
│          Industrial Hardware            │
│ ┌───────────┐ ┌─────────┐ ┌────────────┐│
│ │Temperature│ │ Motors  │ │    I/O     ││
│ │ Sensors   │ │& Pumps  │ │ Controls   ││
│ └───────────┘ └─────────┘ └────────────┘│
└─────────────────────────────────────────┘
```

## Critical System Requirements

### Performance Requirements
- **Real-time Response**: < 100ms for safety-critical operations
- **Temperature Accuracy**: ±0.1°C measurement precision
- **Communication Latency**: < 500ms for Modbus operations
- **UI Responsiveness**: < 50ms touch response time

### Reliability Requirements
- **Uptime**: 99.9% availability during production hours
- **Error Recovery**: Automatic recovery from communication failures
- **Data Integrity**: No loss of configuration or recipe data
- **Safety**: Fail-safe operation on any system error

### Environmental Requirements
- **Operating Temperature**: 0°C to 50°C
- **Humidity**: 10% to 90% non-condensing
- **Vibration**: Industrial environment tolerance
- **Power**: 24V DC industrial power supply

## Migration Considerations

### Current Architecture Issues
1. **Monolithic Design**: Single large class handling multiple concerns
2. **Thread Safety**: Shared state without proper synchronization
3. **Error Handling**: Inconsistent exception management
4. **Testing**: No unit tests for critical control logic
5. **Configuration**: CSV-based storage lacks validation
6. **Communication**: Limited error recovery mechanisms

### Recommended Target Architecture
1. **Microservices**: Separate services for UI, control, and communication
2. **Message Queue**: Decoupled communication between components
3. **Database**: Structured configuration and recipe storage
4. **State Machine**: Formal recipe phase management
5. **Logging**: Comprehensive system monitoring
6. **Testing**: Full test coverage for control logic

This specification provides the foundation for understanding the current system and planning a migration to a more maintainable and robust architecture.