(backend) introduce a configurable analytics system

Add an analytics abstraction that allows configuring which analytics
solution the app uses. PostHog is implemented as one backend, but by
default no analytics backend is activated.

The goal is to track events in a sufficiently organized way and to
let any developer implement their own backend as long as it follows
the same protocol.
This commit is contained in:
lebaudantoine
2026-07-01 18:33:12 +02:00
committed by aleb_the_flash
parent be0d0927d4
commit 9ba97fd14f
7 changed files with 464 additions and 0 deletions
+50
View File
@@ -0,0 +1,50 @@
"""Analytics backend protocol and default no-op implementation."""
from typing import Any, Protocol
from ..models import User
from .events import AnalyticsEvent
class AnalyticsBackend(Protocol):
"""
Interface every analytics backend must implement.
Backends are instantiated once (singleton) with the kwargs declared in
settings.ANALYTICS_BACKEND_SETTINGS, e.g.:
ANALYTICS_BACKEND = "core.analytics.posthog.PostHogAnalytics"
ANALYTICS_BACKEND_SETTINGS = {"api_key": "...", "host": "..."}
"""
def __init__(self, **kwargs: Any) -> None: ...
def identify(self, user: User, properties: dict[str, Any] | None = None) -> None:
"""Associate traits (email, name, ...) with an identified user."""
def capture(
self,
user: User,
event: AnalyticsEvent,
properties: dict[str, Any] | None = None,
) -> None:
"""Record an event performed by an identified user."""
def shutdown(self) -> None:
"""Flush pending events. Called on process exit."""
class NoOpAnalytics:
"""Default backend: silently discards everything."""
def __init__(self, **kwargs: Any) -> None:
"""No-op: accepts and ignores any backend settings kwargs."""
def identify(self, user: User, properties=None) -> None:
"""No-op: discards identify calls."""
def capture(self, user, event, properties=None) -> None:
"""No-op: discards captured events."""
def shutdown(self) -> None:
"""No-op: nothing to flush."""