Add targeted comments for non-obvious constraints and invariants

- logger.py: note why log path uses abspath(__file__) instead of a relative path
- token.py: note why [7:] slice is safe (startswith already verified)
- ipcalc.py: explain /32 single-host and /31 RFC-3021 point-to-point special
  cases; explain why (~netmask) must be masked with 0xFFFFFFFF (Python ~int
  returns a negative arbitrary-precision value, not a 32-bit unsigned integer)
- notes.py: document the module-level _table_ready flag lifetime; explain why
  tzinfo is stripped before passing datetime to mysql-connector
- admin.py: document the module-level _tables_initialized flag lifetime

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/admin.py

@@ -7,6 +7,9 @@ from util.logger import logger
 admin_bp = Blueprint("admin", __name__)
 
 _VALID_ROLES = {"user", "admin"}
+
+# Module-level flag: DDL runs at most once per process lifetime.
+# Resets automatically on worker restart, which re-triggers the check.
 _tables_initialized = False
 
 

backend/auth/token.py

@@ -18,7 +18,7 @@ def verify_token():
         logger.warning("🔐 Invalid Bearer header")
         return None
 
-    token = auth_header[7:]
+    token = auth_header[7:]  # len("Bearer ") == 7; safe because startswith is verified above
     try:
         decoded = decode(token, SECRET_KEY, algorithms=["HS256"])
         return decoded

backend/tools/ipcalc.py

@@ -26,10 +26,13 @@ def ip_calculate():
 
         # Avoid materialising millions of host objects for large networks.
         if prefix == 32:
+            # Single-host route: the address is both network and host.
             total_hosts = 1
             first_host = str(network.network_address)
             last_host = str(network.network_address)
         elif prefix == 31:
+            # RFC 3021 point-to-point: both addresses are usable hosts,
+            # there is no dedicated network or broadcast address.
             total_hosts = 2
             first_host = str(network.network_address)
             last_host = str(network.broadcast_address)
@@ -39,6 +42,8 @@ def ip_calculate():
             last_host = str(ipaddress.IPv4Address(bcast_int - 1))
 
         netmask_int = int(network.netmask)
+        # Python's ~ on an int yields a negative arbitrary-precision value;
+        # mask to 32 bits to get the correct unsigned wildcard address.
         wildcard = str(ipaddress.IPv4Address((~netmask_int) & 0xFFFFFFFF))
         ip_class = "Privat" if network.is_private else "Öffentlich"
 

backend/tools/notes.py

@@ -6,6 +6,8 @@ from auth.token import verify_token
 
 notes_blueprint = Blueprint('notes_tool', __name__)
 
+# Module-level flag: DDL runs at most once per process lifetime.
+# Resets automatically on worker restart, which re-triggers the check.
 _table_ready = False
 
 
@@ -106,6 +108,8 @@ def update_note(note_id):
         title = data.get("title", "").strip() or "Neue Notiz"
         content = data.get("content", "")
         language = data.get("language", "text")
+        # mysql-connector expects a naive datetime for DATETIME columns;
+        # strip tzinfo after converting to UTC to avoid driver warnings.
         now = datetime.now(timezone.utc).replace(tzinfo=None)
 
         conn = get_connection()

backend/util/logger.py

@@ -2,6 +2,7 @@ import logging
 import os
 from logging.handlers import RotatingFileHandler
 
+# Absolute path so the log dir is always next to this file, regardless of CWD.
 _LOG_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "logs")
 os.makedirs(_LOG_DIR, exist_ok=True)