Add documentation about datetime handling

src/ddns_service/__init__.py

@@ -43,8 +43,26 @@ __all__ = [
 
 DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S %Z"
 
+# Datetime convention:
+# All datetime objects in this codebase are naive UTC to match database storage.
+# - utc_now(): returns naive UTC datetime
+# - datetime_str(): converts naive UTC to display string (adds tzinfo for formatting)
+# - Database stores/returns naive datetimes (always UTC by convention)
+
 
 def datetime_str(dt, utc=False):
+    """
+    Convert datetime to display string.
+
+    Assumes naive datetimes are UTC per codebase convention.
+
+    Args:
+        dt: Datetime object (naive UTC or timezone-aware).
+        utc: If True, display in UTC; otherwise convert to local timezone.
+
+    Returns:
+        Formatted datetime string, or "Never" if dt is not a datetime.
+    """
     if not isinstance(dt, datetime.datetime):
         return "Never"
 
@@ -57,4 +75,10 @@ def datetime_str(dt, utc=False):
 
 
 def utc_now():
+    """
+    Get current time as naive UTC datetime.
+
+    Returns naive datetime to match database storage behavior.
+    All naive datetimes in this codebase are assumed to be UTC.
+    """
     return datetime.datetime.now(datetime.UTC).replace(tzinfo=None)