first commit

backend/app/domain/observability.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(slots=True)
+class AuditLogEntry:
+    """Business-level audit record for operator actions."""
+
+    action: str
+    actor_id: str | None = None
+    actor_email: str | None = None
+    target_type: str | None = None
+    target_id: str | None = None
+    source: str = "fastapi"
+    result: str = "accepted"
+    meta: dict[str, Any] | list[Any] | None = None
+    request_id: str | None = None
+    created_at: datetime = field(default_factory=utcnow)
+    id: str = field(default_factory=lambda: str(uuid4()))
+
+
+@dataclass(slots=True)
+class SystemEvent:
+    """System/runtime event used for telemetry and forwarding pipelines."""
+
+    event_name: str
+    category: str
+    request_id: str | None = None
+    site_id: str | None = None
+    site_key: str | None = None
+    experiment_id: str | None = None
+    experiment_key: str | None = None
+    variant_id: str | None = None
+    variant_key: str | None = None
+    visitor_id: str | None = None
+    payload: dict[str, Any] | list[Any] | None = None
+    created_at: datetime = field(default_factory=utcnow)
+    id: str = field(default_factory=lambda: str(uuid4()))
+