# Calejo Control Adapter - System Architecture ## Overview The Calejo Control Adapter is a multi-protocol integration adapter designed for municipal wastewater pump stations. It translates optimized pump control plans from Calejo Optimize into real-time control signals while maintaining comprehensive safety and security compliance. **Key Design Principles:** - **Safety First**: Multi-layer safety architecture with failsafe mechanisms - **Security by Design**: Built-in security controls compliant with industrial standards - **Protocol Agnostic**: Support for multiple industrial protocols simultaneously - **High Availability**: Redundant components and health monitoring - **Transparent Operations**: Comprehensive audit logging and monitoring ## System Architecture ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ Calejo Optimize Container (Existing) │ │ - Optimization Engine │ │ - PostgreSQL Database (pump plans) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ Calejo Control Adapter (IMPLEMENTED) │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ Core Components: │ │ │ │ 1. Auto-Discovery Module ✅ │ │ │ │ 2. Safety Framework ✅ │ │ │ │ 3. Emergency Stop Manager ✅ │ │ │ │ 4. Optimization Plan Manager ✅ │ │ │ │ 5. Setpoint Manager ✅ │ │ │ │ 6. Database Watchdog ✅ │ │ │ │ 7. Alert Manager ✅ │ │ │ │ 8. Multi-Protocol Server ✅ │ │ │ │ - OPC UA Server │ │ │ │ - Modbus TCP Server │ │ │ │ - REST API │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ↓ (Multiple Protocols) ↓ ┌─────────────────┼─────────────────┐ ↓ ↓ ↓ Siemens WinCC Schneider EcoStruxure Rockwell FactoryTalk ``` ## Component Architecture ### Core Components #### 1. Auto-Discovery Module (`src/core/auto_discovery.py`) - **Purpose**: Automatically discovers pump stations and pumps from database - **Features**: - Dynamic discovery of pump configurations - Periodic refresh of station information - Integration with safety framework - **Configuration**: Refresh interval configurable via settings #### 2. Safety Framework (`src/core/safety.py`) - **Purpose**: Multi-layer safety enforcement for all setpoints - **Three-Layer Architecture**: - **Layer 1**: Physical Hard Limits (PLC/VFD) - 15-55 Hz - **Layer 2**: Station Safety Limits (Database) - 20-50 Hz (enforced here) - **Layer 3**: Optimization Constraints (Calejo Optimize) - 25-45 Hz - **Features**: - Rate of change limiting - Emergency stop integration - Failsafe mode activation #### 3. Emergency Stop Manager (`src/core/emergency_stop.py`) - **Purpose**: Manual override capability for emergency situations - **Features**: - Station-level and pump-level emergency stops - Automatic setpoint override to 0 Hz - Manual reset capability - Audit logging of all emergency operations #### 4. Optimization Plan Manager (`src/core/optimization_manager.py`) - **Purpose**: Manages optimization plans from Calejo Optimize - **Features**: - Periodic polling of optimization database - Plan validation and safety checks - Integration with setpoint manager - Plan execution monitoring #### 5. Setpoint Manager (`src/core/setpoint_manager.py`) - **Purpose**: Calculates and manages real-time setpoints - **Calculator Types**: - `DIRECT_SPEED`: Direct speed control - `LEVEL_CONTROLLED`: Level-based control with feedback - `POWER_CONTROLLED`: Power-based control with feedback - **Features**: - Real-time setpoint calculation - Integration with safety framework - Performance monitoring ### Security Components #### 6. Security Manager (`src/core/security.py`) - **Purpose**: Unified security management - **Components**: - **Authentication Manager**: JWT-based authentication with bcrypt password hashing - **Authorization Manager**: Role-based access control (RBAC) - **Security Manager**: Coordination of authentication and authorization - **User Roles**: - `READ_ONLY`: Read-only access to system status - `OPERATOR`: Basic operational controls including emergency stop - `ENGINEER`: Configuration and safety limit management - `ADMINISTRATOR`: Full system access including user management #### 7. Compliance Audit Logger (`src/core/compliance_audit.py`) - **Purpose**: Comprehensive audit logging for regulatory compliance - **Supported Standards**: - IEC 62443 (Industrial Automation and Control Systems Security) - ISO 27001 (Information Security Management) - NIS2 Directive (Network and Information Systems Security) - **Features**: - Immutable audit trail - Event categorization by severity - Compliance reporting - Database and structured logging #### 8. TLS Manager (`src/core/tls_manager.py`) - **Purpose**: Certificate-based encryption management - **Features**: - Certificate generation and rotation - TLS/SSL configuration - Certificate validation - Secure communication channels ### Protocol Servers #### 9. OPC UA Server (`src/protocols/opcua_server.py`) - **Purpose**: Industrial automation protocol support - **Features**: - OPC UA 1.04 compliant server - Node caching for performance - Security policy support - Certificate-based authentication - **Endpoints**: `opc.tcp://0.0.0.0:4840` #### 10. Modbus TCP Server (`src/protocols/modbus_server.py`) - **Purpose**: Legacy industrial protocol support - **Features**: - Modbus TCP protocol implementation - Connection pooling - Industrial security features - High-performance data access - **Port**: 502 #### 11. REST API Server (`src/protocols/rest_api.py`) - **Purpose**: Modern web API for integration - **Features**: - OpenAPI documentation - Response caching - Compression support - Rate limiting - **Port**: 8080 ### Monitoring Components #### 12. Database Watchdog (`src/monitoring/watchdog.py`) - **Purpose**: Ensures database connectivity and failsafe operation - **Features**: - Periodic health checks - Automatic failsafe activation - Alert generation on connectivity loss - Graceful degradation #### 13. Alert Manager (`src/monitoring/alerts.py`) - **Purpose**: Comprehensive alerting system - **Features**: - Multi-channel notifications (email, SMS, webhook) - Alert escalation - Alert history and management - Integration with audit system #### 14. Health Monitor (`src/monitoring/health_monitor.py`) - **Purpose**: System health monitoring and metrics - **Features**: - Component health status - Performance metrics - Resource utilization - External health check endpoints ## Data Flow Architecture ### Setpoint Calculation Flow ``` 1. Optimization Plan Polling ↓ 2. Plan Validation & Safety Check ↓ 3. Setpoint Calculation ↓ 4. Safety Limit Enforcement ↓ 5. Protocol Server Distribution ↓ 6. SCADA System Integration ``` ### Safety Enforcement Flow ``` 1. Proposed Setpoint ↓ 2. Emergency Stop Check (Highest Priority) ↓ 3. Hard Limit Enforcement ↓ 4. Rate of Change Limiting ↓ 5. Final Setpoint Validation ↓ 6. Protocol Server Delivery ``` ## Security Architecture ### Authentication & Authorization - **JWT-based Authentication**: Secure token-based authentication - **Role-Based Access Control**: Granular permissions per user role - **Certificate Authentication**: For industrial protocol security - **Session Management**: Secure session handling with timeout ### Encryption & Communication Security - **TLS/SSL Encryption**: All external communications - **Certificate Management**: Automated certificate rotation - **Secure Protocols**: Industry-standard security protocols - **Network Segmentation**: Zone-based security model ### Audit & Compliance - **Comprehensive Logging**: All security-relevant events - **Immutable Audit Trail**: Tamper-resistant logging - **Compliance Reporting**: Automated compliance reports - **Security Monitoring**: Real-time security event monitoring ## Deployment Architecture ### Container Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ Calejo Control Adapter Container │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ OPC UA Server │ │ Modbus Server │ │ │ │ Port: 4840 │ │ Port: 502 │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ REST API │ │ Health Monitor │ │ │ │ Port: 8080 │ │ Port: 8081 │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Core Application Components │ │ │ │ - Safety Framework │ │ │ │ - Security Layer │ │ │ │ - Monitoring & Alerting │ │ │ └─────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` ### High Availability Features - **Database Connection Pooling**: Optimized database connectivity - **Component Health Monitoring**: Continuous health checks - **Graceful Degradation**: Failsafe operation on component failure - **Automatic Recovery**: Self-healing capabilities - **Load Balancing**: Protocol server load distribution ## Performance & Scalability ### Performance Characteristics - **Setpoint Calculation**: < 100ms per pump - **Protocol Response Time**: < 50ms for OPC UA/Modbus - **Database Operations**: Optimized connection pooling - **Memory Usage**: Efficient caching and resource management ### Scalability Features - **Horizontal Scaling**: Multiple adapter instances - **Load Distribution**: Protocol-specific load balancing - **Resource Optimization**: Dynamic resource allocation - **Performance Monitoring**: Real-time performance metrics ## Integration Patterns ### SCADA System Integration - **OPC UA Integration**: Standard industrial protocol - **Modbus Integration**: Legacy system compatibility - **REST API Integration**: Modern web services - **Database Integration**: Direct database access ### External System Integration - **Alert Systems**: Email, SMS, webhook integration - **Monitoring Systems**: Health check endpoints - **Security Systems**: Integration with enterprise security - **Compliance Systems**: Audit log export and reporting ## Configuration Management ### Configuration Sources - **Environment Variables**: Primary configuration method - **Configuration Files**: YAML/JSON configuration support - **Database Configuration**: Dynamic configuration updates - **Runtime Configuration**: Hot-reload capability for certain settings ### Key Configuration Areas - **Database Connection**: Connection strings and pooling - **Safety Limits**: Station and pump-specific safety parameters - **Security Settings**: Authentication and authorization configuration - **Protocol Settings**: Protocol-specific configuration - **Monitoring Settings**: Alert thresholds and monitoring intervals ## Development & Testing Architecture ### Testing Framework - **Unit Tests**: Component-level testing - **Integration Tests**: Component interaction testing - **End-to-End Tests**: Complete workflow testing - **Deployment Tests**: Production environment validation - **Security Tests**: Security control validation ### Development Workflow - **Code Quality**: Linting, type checking, formatting - **Continuous Integration**: Automated testing pipeline - **Documentation**: Comprehensive documentation generation - **Release Management**: Version control and release process ## Compliance & Certification ### Regulatory Compliance - **IEC 62443**: Industrial automation security - **ISO 27001**: Information security management - **NIS2 Directive**: Network and information systems security - **Industry Standards**: Water/wastewater industry standards ### Certification Strategy - **Security Certification**: IEC 62443 certification process - **Quality Certification**: ISO 9001 quality management - **Industry Certification**: Water industry-specific certifications - **Continuous Compliance**: Ongoing compliance monitoring --- *This architecture document provides a comprehensive overview of the Calejo Control Adapter system architecture. For detailed implementation specifications, refer to the individual component documentation.*