diff --git a/custom_components/tibber_prices/coordinator/__init__.py b/custom_components/tibber_prices/coordinator/__init__.py
index 2b011ae..50fa061 100644
--- a/custom_components/tibber_prices/coordinator/__init__.py
+++ b/custom_components/tibber_prices/coordinator/__init__.py
@@ -1,4 +1,20 @@
-"""Coordinator package for Tibber Prices integration."""
+"""
+Data update coordination package.
+
+This package orchestrates data fetching, caching, and entity updates:
+- API polling at 15-minute intervals
+- Persistent storage via HA Store
+- Quarter-hour entity refresh scheduling
+- Price data enrichment pipeline
+- Period calculation (best/peak price periods)
+
+Main components:
+- core.py: TibberPricesDataUpdateCoordinator (main coordinator class)
+- cache.py: Persistent storage management
+- data_transformation.py: Raw data → enriched data pipeline
+- listeners.py: Entity refresh scheduling
+- period_handlers/: Period calculation sub-package
+"""
 
 from .constants import (
     MINUTE_UPDATE_ENTITY_KEYS,