# System Architecture

## Overview

The home automation system uses a distributed architecture with multiple components communicating over network protocols.

## Component Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    Physical Layer                            │
├─────────────────────────────────────────────────────────────┤
│  Zigbee Switches  │  Relays  │  Water Boiler  │  Lights     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │
┌─────────────────────────────────────────────────────────────┐
│                    Control Layer                             │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌──────────────┐                     │
│  │  CODESYS     │◄────►│  Node-RED    │                     │
│  │  (Raspberry  │      │              │                     │
│  │   Pi)        │      │              │                     │
│  └──────┬───────┘      └──────┬───────┘                     │
│         │                     │                              │
│         │                     │                              │
│  ┌──────▼───────┐      ┌──────▼───────┐                     │
│  │  EtherCAT    │      │   MQTT       │                     │
│  │  IO Card     │      │   Broker     │                     │
│  └──────────────┘      │   (LXC)      │                     │
│                        └──────┬───────┘                     │
│                               │                              │
│                        ┌──────▼───────┐                     │
│                        │ Zigbee2MQTT  │                     │
│                        └──────┬───────┘                     │
│                               │                              │
│                        ┌──────▼───────┐                     │
│                        │ Home         │                     │
│                        │ Assistant    │                     │
│                        └──────────────┘                     │
└─────────────────────────────────────────────────────────────┘
```

## Communication Flow

### Light Switch Control Flow

1. **User Action**: Physical Zigbee switch is pressed
2. **Zigbee2MQTT**: Receives Zigbee message, converts to MQTT
3. **MQTT Broker**: Routes message to subscribers
4. **Node-RED**: Receives MQTT message, processes automation logic
5. **CODESYS**: Node-RED sends network variable to CODESYS
6. **EtherCAT IO**: CODESYS activates relay via EtherCAT
7. **Physical Device**: Relay controls light

### Water Boiler Control Flow

1. **Trigger**: Time-based, sensor-based, or manual trigger
2. **Node-RED/Home Assistant**: Processes automation logic
3. **CODESYS**: Receives control command via network variable
4. **EtherCAT IO**: CODESYS activates relay for boiler
5. **Water Boiler**: Receives control signal

## Protocols Used

- **EtherCAT**: Industrial communication between CODESYS and IO card
- **MQTT**: Message queuing for device communication
- **Zigbee**: Wireless mesh network for switches
- **Network Variables**: CODESYS to Node-RED communication
- **HTTP/REST**: Home Assistant API and Node-RED HTTP nodes

## Data Flow

### Inputs
- Zigbee switch states
- Sensor data (if applicable)
- Time-based triggers
- Manual commands from Home Assistant

### Processing
- Node-RED flows for automation logic
- CODESYS control logic
- Home Assistant automations

### Outputs
- Relay control signals
- Light states
- Water boiler control
- Dashboard updates

## Security Considerations

- MQTT authentication (to be documented)
- Network isolation (to be documented)
- CODESYS access control (to be documented)
- Zigbee network security (to be documented)

## Redundancy and Reliability

- [ ] Backup procedures
- [ ] Failover mechanisms
- [ ] Error recovery
- [ ] Monitoring and alerting

---

**Status**: Initial structure - needs detailed information to complete