15 KiB

Raw Blame History

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.

15 KiB Raw Blame History