heartbeat/REFACTORING.md

# HBD/HBC Separation Refactoring

## Overview

The heartbeat monitoring system has been refactored into a modular package structure with separate client and server components. This allows users to install only what they need and provides clear separation of concerns.

## New Package Structure

```
hbd/
├── __init__.py                 # Main package (minimal)
├── client/                     # HBC - System monitoring client
│   ├── __init__.py
│   ├── main.py                # Entry point (was hbc.py)
│   ├── config.py              # Client-specific configuration
│   ├── plugin.py              # Plugin framework
│   ├── threshold.py           # Threshold checking
│   └── plugins/               # Monitoring plugins
│       ├── cpu_monitor.py
│       ├── disk_monitor.py
│       ├── memory_monitor.py
│       ├── network_monitor.py
│       ├── filesystem_info.py
│       ├── os_info.py
│       └── nagios_runner.py
├── server/                     # HBD - Heartbeat daemon/server
│   ├── __init__.py
│   ├── main.py                # Server runtime (was server.py)
│   ├── cli.py                 # Command-line interface
│   ├── config.py              # Server-specific configuration
│   ├── http.py                # HTTP/REST API
│   ├── ws.py                  # WebSocket server
│   ├── udp.py                 # UDP heartbeat listener
│   ├── dns.py                 # DNS update functionality
│   ├── notify.py              # Notification handlers
│   ├── monitor.py             # Host monitoring
│   ├── hbdclass.py            # Host class definitions
│   ├── journal.py             # Message journaling
│   ├── templates/             # Jinja2 web templates
│   └── static/                # Web UI assets
└── common/                     # Shared utilities
    ├── __init__.py
    ├── proto.py               # Protocol encoding/decoding
    └── utils.py               # Common utilities

## Configuration Files

### Client Configuration (hbd/client/config.py)

Client-specific defaults:
- `hb_port`: Port where hbd servers listen (default: 50003)
- `interval`: Heartbeat interval in seconds (default: 10)
- `plugins`: Per-plugin configuration
- `thresholds`: Threshold configuration for monitoring

### Server Configuration (hbd/server/config.py)

Server-specific defaults:
- `hb_port`: Port to listen for heartbeats (default: 50003)
- `hbd_port`: HTTP API port (default: 50004)
- `ws_port`: WebSocket port (default: 50005)
- `logfile`: Log file path
- `pushsrv`, `pushover_token`, etc.: Notification settings
- `watchhosts`, `dyndnshosts`: Host monitoring
- `smtpserver`, etc.: Email settings
- `journal_*`: Message journaling settings

## Installation Options

### Install Core Only (minimal, PyYAML only)
```bash
pip install hbd
```

### Install Client Only (for monitoring)
```bash
pip install hbd[client]
# Installs: PyYAML, psutil
```

### Install Server Only (for daemon)
```bash
pip install hbd[server]
# Installs: PyYAML, websockets, mattermostdriver, aiohttp, Jinja2
```

### Install Everything
```bash
pip install hbd[all]
# Installs all dependencies for both client and server
```

### Development Installation
```bash
pip install -e ".[dev]"
# Includes all dependencies plus testing/linting tools
```

## Command-Line Interfaces

### HBC (Client)
```bash
hbc [options] host1 [host2 ...]

# Entry point: hbd.client.main:main
# Location: hbd/client/main.py
```

### HBD (Server)
```bash
hbd [options]

# Entry point: hbd.server.cli:main
# Location: hbd/server/cli.py → hbd/server/main.py
```

## Import Changes

### Client Code
```python
# Old imports
from .config import load_config
from .proto import dicttos, stodict
from .plugin import PluginRegistry

# New imports
from .config import load_config          # Still in client/
from ..common.proto import dicttos       # Moved to common/
from .plugin import PluginRegistry       # Still in client/
```

### Server Code
```python
# Old imports
from .config import load_config
from .proto import stodict
from .threshold import AlertLevel

# New imports
from .config import load_config          # Server-specific config
from ..common.proto import stodict       # Moved to common/
from ..client.threshold import AlertLevel # Client module
```

### Plugin Code
```python
# Old import
from hbd.plugin import MonitorPlugin

# New import
from hbd.client.plugin import MonitorPlugin
```

## Benefits

1. **Modular Installation**: Install only what you need
   - Client-only systems don't need web server dependencies
   - Server-only systems don't need psutil
   
2. **Clearer Architecture**: Explicit separation of concerns
   - Client: System monitoring and data collection
   - Server: Heartbeat reception, web UI, notifications
   - Common: Shared protocol and utilities

3. **Independent Evolution**: Client and server can evolve separately
   - Different release cycles possible
   - Clear API boundaries via common/

4. **Smaller Footprint**: Reduced dependency installation
   - Client: ~1 dependency (psutil)
   - Server: ~4 dependencies (websockets, aiohttp, Jinja2, mattermostdriver)

## Migration Guide

### For Existing Installations

1. **Reinstall the package**:
   ```bash
   pip install -e ".[all]"  # For development
   # or
   pip install hbd[all]     # For production
   ```

2. **Configuration files remain unchanged**:
   - Both client and server read from `~/.hb.yaml`
   - All existing config keys are supported in both configs
   - Server has additional keys (journal, websocket, email, etc.)
   - Client has minimal keys (interval, plugins, thresholds)

3. **Commands remain the same**:
   - `hbc` command works identically
   - `hbd` command works identically

### For New Deployments

1. **Client-only system** (monitoring host):
   ```bash
   pip install hbd[client]
   hbc server1.example.com server2.example.com
   ```

2. **Server-only system** (monitoring daemon):
   ```bash
   pip install hbd[server]
   hbd -c /etc/hbd.yaml -f
   ```

3. **Combined system** (dev/test):
   ```bash
   pip install hbd[all]
   ```

## Testing

All imports and entry points have been tested and validated:
- ✅ Package imports work correctly
- ✅ `hbc` command entry point functional
- ✅ `hbd` command entry point functional
- ✅ Optional dependencies properly configured
- ✅ All internal imports updated

## Files Archived

The following files were renamed to avoid conflicts:
- `hbd/config.py` → `hbd/config.py.old` (split into client/server configs)
- `hbd/hbc_old.py` → `hbd/hbc_old.py.bak` (backup file)

## Next Steps

1. Test client functionality with a monitoring host
2. Test server functionality with web UI and notifications
3. Update documentation (README.md) with new structure
4. Consider publishing to PyPI with new structure
5. Update any deployment scripts/Dockerfiles to use optional dependencies