diff --git a/README.md b/README.md
index 847fe09..a63d5df 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ See [docs/NAGIOS_INTEGRATION.md](docs/NAGIOS_INTEGRATION.md) for complete integr
 ### Creating Custom Plugins
 
 ```python
-from hbd.plugin import MonitorPlugin
+from hbd.client.plugin import MonitorPlugin
 
 class DiskMonitorPlugin(MonitorPlugin):
     name = "disk_monitor"
@@ -89,7 +89,7 @@ class DiskMonitorPlugin(MonitorPlugin):
         }
 ```
 
-Place plugins in `hbd/plugins/` and they'll be automatically discovered and loaded by the client.
+Place plugins in `hbd/client/plugins/` and they'll be automatically discovered and loaded by the client.
 
 ---
 
@@ -368,7 +368,7 @@ See [docs/HTTP_API.md](docs/HTTP_API.md) for complete API documentation includin
 
 Prerequisites:
 
-- Python 3.10+ (project uses language features from recent Python)
+- Python 3.11+ (project uses language features from recent Python)
 - `nsupdate` (for DNS updates) if using dynamic DNS
 
 Install dependencies (recommended into a venv):
@@ -389,7 +389,7 @@ hbd -c .hb.yaml -f -v
 You can also run it directly via the package entrypoint after installation:
 
 ```bash
-python -m hbd.cli -c /path/to/config.yaml
+python -m hbd.server.cli -c /path/to/config.yaml
 ```
 
 ### Running the Client
@@ -397,14 +397,23 @@ python -m hbd.cli -c /path/to/config.yaml
 The heartbeat client (`hbc`) sends periodic heartbeats and plugin data to the server:
 
 ```bash
-# Basic usage pointing to server
-python -m hbd.hbc --server your-server.example.com
+# Basic usage pointing to server (host is a positional argument)
+hbc your-server.example.com
 
-# With custom configuration
-python -m hbd.hbc --server 192.168.1.100 --port 50003 --interval 30
+# Run as daemon with a config file
+hbc -d -c /etc/hbc.yaml your-server.example.com
 
-# Run with specific plugins enabled/disabled
-python -m hbd.hbc --server hbd.local --disable-plugin os_info
+# Send a one-off boot message
+hbc --boot your-server.example.com
+
+# Verbose output
+hbc -v your-server.example.com
+```
+
+You can also run it via the module entrypoint:
+
+```bash
+python -m hbd.client.main your-server.example.com
 ```
 
 Client configuration can also be specified in YAML:
@@ -438,23 +447,23 @@ This repository includes a ready-to-use `.vscode/launch.json` with configuration
 
 - Ensure the **Python** extension is installed and select the project `.venv` as the interpreter (bottom-left of VS Code).
 - Use **F5** and pick one of these configurations from the Run view:
-  - **Python: Run hbd (module)** — runs `hbd.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
+  - **Python: Run hbd (module)** — runs `hbd.server.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
   - **Python: Run hbd with debugpy (listen)** — launches `debugpy` and `hbd` together; useful when you want the process to listen for a debugger.
   - **Python: Attach (localhost:5678)** — attach the debugger to a running process started with `debugpy`.
 
 To start `hbd` manually and wait for the debugger to attach, run:
 
 ```bash
-PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.cli -c .hb.yaml -f -v
+PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.server.cli -c .hb.yaml -f -v
 ```
 
-Set breakpoints in modules such as `hbd/udp.py`, `hbd/dns.py`, or `hbd/server.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
+Set breakpoints in modules such as `hbd/server/udp.py`, `hbd/server/dns.py`, or `hbd/server/main.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
 
 ---
 
 ## 🛠 Configuration
 
-`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/config.py`):
+`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/server/config.py`):
 
 - `hb_port`: UDP port to listen for heartbeats (default: 50003)
 - `hbd_port`: internal control port (default: 50004)
@@ -487,29 +496,39 @@ nsupdate_bin: /usr/bin/nsupdate
 pushsrv: pushover
 ```
 
-> Tip: `config.DEFAULTS` in `hbd/config.py` contains the canonical defaults and accepted configuration keys.
+> Tip: `SERVER_DEFAULTS` in `hbd/server/config.py` contains the canonical defaults and accepted configuration keys.
 
 ---
 
 ## 🔧 Architecture & Modules
 
-- `hbd.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
-- `hbd.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
-- `hbd.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
-  The DNS worker now runs as an `asyncio` task and the package exposes a
-  small thread-safe bridge so legacy synchronous code can `put()` updates
-  into the queue; there is no longer a permanently-blocking background
-  `threading.Thread`.
-- `hbd.notify` — email and push notification helpers
-- `hbd.ws` — WebSocket server and thread-safe broadcast helpers
-- `hbd.http` — HTTP handler factory for the status UI/API
-- `hbd.journal` — message journal with size-based log rotation and backup management
-- `hbd.plugin` — plugin framework with base classes, registry, and dynamic loader
-- `hbd.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
-- `hbd.hbc` — heartbeat client that sends heartbeats and plugin data to server
-- `hbd.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
-- `hbd.cli` — CLI entrypoint and argument parsing
-- `hbd.server` — async orchestration to run UDP/HTTP/WSS components
+The package is organized into three subpackages:
+
+**`hbd.common`** — shared code used by both client and server:
+- `hbd.common.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
+- `hbd.common.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
+
+**`hbd.server`** — the heartbeat daemon (`hbd`):
+- `hbd.server.cli` — CLI entrypoint and argument parsing
+- `hbd.server.main` — async orchestration to run UDP/HTTP/WSS components
+- `hbd.server.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
+- `hbd.server.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
+  The DNS worker runs as an `asyncio` task and the package exposes a small thread-safe bridge
+  so legacy synchronous code can `put()` updates into the queue.
+- `hbd.server.notify` — email and push notification helpers
+- `hbd.server.ws` — WebSocket server and thread-safe broadcast helpers
+- `hbd.server.http` — HTTP handler factory for the status UI/API
+- `hbd.server.journal` — message journal with size-based log rotation and backup management
+- `hbd.server.threshold` — threshold alerting engine
+- `hbd.server.monitor` — host state monitoring
+- `hbd.server.hbdclass` — `Host` class and shared server state
+- `hbd.server.config` — configuration loader and defaults
+
+**`hbd.client`** — the heartbeat client (`hbc`):
+- `hbd.client.main` — client entrypoint; sends heartbeats and plugin data to the server
+- `hbd.client.plugin` — plugin framework with base classes, registry, and dynamic loader
+- `hbd.client.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
+- `hbd.client.config` — client configuration loader
 
 This modular layout makes the code easier to test and maintain.
 
@@ -517,12 +536,12 @@ This modular layout makes the code easier to test and maintain.
 
 - The main runtime is asyncio-based. Services (UDP listener, HTTP server, WebSocket server, monitor, and DNS worker) run as asyncio tasks.
 - On SIGINT/SIGTERM the server triggers a graceful shutdown: it cancels active tasks, signals the DNS worker via a sentinel, and cleans up resources before exit.
-- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.hbdclass.Host.dnsQ`.
+- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.server.hbdclass.Host.dnsQ`.
 
 **Templates & Static Files**
 
-- Template files are located under `hbd/templates` by default. The HTTP server resolves templates relative to the `hbd` package but the path can be overridden with the `templates_dir` config key.
-- Static assets (CSS/JS/images) are served from `hbd/static` via the `/static/<path>` HTTP route. Place your static files in that directory or configure the HTTP server as needed.
+- Template files are located under `hbd/server/templates`. The HTTP server resolves templates relative to the `hbd.server` package but the path can be overridden with the `templates_dir` config key.
+- Static assets (CSS/JS/images) are served from `hbd/server/static` via the `/static/<path>` HTTP route.
 
 ---