first commit

backend/app/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer packages."""

backend/app/application/admin/__init__.py

@@ -0,0 +1 @@
+"""Admin application services."""

backend/app/application/admin/activity.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.repositories.directus.activity import DirectusActivityRepository
+from app.repositories.directus.variants import VariantRepository
+from app.repositories.directus.releases import ReleaseRepository
+
+ACTION_LABELS: dict[str, str] = {
+    "create": "建立",
+    "update": "更新",
+    "delete": "刪除",
+}
+
+COLLECTION_LABELS: dict[str, str] = {
+    "experiments": "實驗設定",
+    "variants": "變體",
+    "experiment_releases": "版本",
+    "variant_changes": "視覺變更",
+}
+
+
+class ActivityService:
+    def __init__(
+        self,
+        activity_repository: DirectusActivityRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+        release_repository: ReleaseRepository | None = None,
+    ) -> None:
+        self.activity_repo = activity_repository or DirectusActivityRepository()
+        self.variant_repo = variant_repository or VariantRepository()
+        self.release_repo = release_repository or ReleaseRepository()
+
+    async def list_for_experiment(
+        self,
+        experiment_id: str,
+        access_token: str | None = None,
+    ) -> list[dict[str, Any]]:
+        # Collect all item IDs related to this experiment
+        item_ids: list[str] = [experiment_id]
+
+        variants = await self.variant_repo.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "fields": "id"},
+            access_token=access_token,
+        )
+        variant_ids = [str(v["id"]) for v in variants]
+        item_ids.extend(variant_ids)
+
+        releases = await self.release_repo.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "fields": "id"},
+            access_token=access_token,
+        )
+        release_ids = [str(r["id"]) for r in releases]
+        item_ids.extend(release_ids)
+
+        raw_entries = await self.activity_repo.list_for_items(
+            item_ids=item_ids,
+            access_token=access_token,
+        )
+
+        result = []
+        for entry in raw_entries:
+            action = str(entry.get("action", ""))
+            collection = str(entry.get("collection", ""))
+            user = entry.get("user") or {}
+            actor_email = user.get("email") if isinstance(user, dict) else None
+            actor_id = user.get("id") if isinstance(user, dict) else str(user) if user else None
+
+            result.append({
+                "id": entry.get("id"),
+                "action": action,
+                "action_label": ACTION_LABELS.get(action, action),
+                "collection": collection,
+                "collection_label": COLLECTION_LABELS.get(collection, collection),
+                "item": str(entry.get("item", "")),
+                "timestamp": entry.get("timestamp"),
+                "actor_email": actor_email,
+                "actor_id": actor_id,
+            })
+
+        return result

backend/app/application/admin/experiments.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.domain.keys import generate_experiment_key, generate_variant_key
+from app.domain.mappers import to_experiment
+from app.repositories.directus.experiments import ExperimentRepository
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import ExperimentCreate, ExperimentRead, ExperimentUpdate, experiment_to_read_model
+
+
+class ExperimentService:
+    """Application service for experiment use-cases.
+
+    This is where we will keep:
+    - validation
+    - permission checks
+    - state transitions
+    - orchestration before writing to Directus
+    """
+
+    def __init__(
+        self,
+        repository: ExperimentRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+    ) -> None:
+        self.repository = repository or ExperimentRepository()
+        self.variant_repository = variant_repository or VariantRepository()
+
+    async def list_experiments(self, access_token: str | None = None) -> list[ExperimentRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [experiment_to_read_model(to_experiment(item)) for item in items]
+
+    async def get_experiment(
+        self,
+        experiment_id: str,
+        access_token: str | None = None,
+    ) -> ExperimentRead | None:
+        item = await self.repository.get(experiment_id, access_token=access_token)
+        if not item:
+            return None
+        return experiment_to_read_model(to_experiment(item))
+
+    async def create_experiment(
+        self,
+        payload: ExperimentCreate,
+        access_token: str | None = None,
+    ) -> ExperimentRead:
+        data: dict[str, Any] = payload.model_dump(exclude_none=True)
+        data["experiment_key"] = generate_experiment_key()
+        item = await self.repository.create(data, access_token=access_token)
+        experiment = to_experiment(item)
+
+        # Auto-create 原始版本 (control) variant
+        await self.variant_repository.create(
+            {
+                "experiment_id": experiment.id,
+                "variant_key": generate_variant_key(),
+                "name": "原始版本",
+                "traffic_weight": 50,
+            },
+            access_token=access_token,
+        )
+
+        return experiment_to_read_model(experiment)
+
+    async def update_experiment(
+        self,
+        experiment_id: str,
+        payload: ExperimentUpdate,
+        access_token: str | None = None,
+    ) -> ExperimentRead | None:
+        data: dict[str, Any] = payload.model_dump(exclude_unset=True)
+        item = await self.repository.update(experiment_id, data, access_token=access_token)
+        if not item:
+            return None
+        return experiment_to_read_model(to_experiment(item))

backend/app/application/admin/goals.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.domain.mappers import to_goal
+from app.repositories.directus.goals import GoalRepository
+from app.schemas.admin import GoalRead, goal_to_read_model
+
+
+class GoalService:
+    """Application service for experiment goal management."""
+
+    def __init__(self, repository: GoalRepository | None = None) -> None:
+        self.repository = repository or GoalRepository()
+
+    async def list_goals(
+        self,
+        site_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[GoalRead]:
+        params: dict[str, Any] | None = None
+        if site_id:
+            params = {"filter[site_id][_eq]": site_id}
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [goal_to_read_model(to_goal(item)) for item in items]
+
+    async def get_goal(
+        self,
+        goal_id: str,
+        access_token: str | None = None,
+    ) -> GoalRead | None:
+        item = await self.repository.get(goal_id, access_token=access_token)
+        if not item:
+            return None
+        return goal_to_read_model(to_goal(item))

backend/app/application/admin/marketing_cards.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from app.repositories.directus.marketing_cards import MarketingCardRepository
+from app.schemas.marketing_card import MarketingCardRead
+
+
+class MarketingCardService:
+    """Application service for the current marketing-card module.
+
+    This keeps the legacy module reachable while frontend migration is in
+    progress. Later we can either map it into experiment/variant concepts or
+    retire it after the new module replaces it.
+    """
+
+    def __init__(self, repository: MarketingCardRepository | None = None) -> None:
+        self.repository = repository or MarketingCardRepository()
+
+    async def list_marketing_cards(self) -> list[MarketingCardRead]:
+        items = await self.repository.list()
+        return [MarketingCardRead.model_validate(item) for item in items]
+
+    async def get_marketing_card(self, card_id: str) -> MarketingCardRead | None:
+        item = await self.repository.get(card_id)
+        if not item:
+            return None
+        return MarketingCardRead.model_validate(item)
+

backend/app/application/admin/releases.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from app.domain.editor import VariantChange
+from app.domain.editor_builder import build_runtime_payload_from_changes
+from app.domain.mappers import to_release
+from app.repositories.directus.releases import ReleaseRepository
+from app.repositories.directus.variant_changes import VariantChangeRepository
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import BuildReleaseRequest, ReleaseLifecycleResponse, ReleaseRead, release_to_read_model
+
+
+class ReleaseService:
+    """Application service for release and snapshot lifecycle."""
+
+    def __init__(
+        self,
+        repository: ReleaseRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+        change_repository: VariantChangeRepository | None = None,
+    ) -> None:
+        self.repository = repository or ReleaseRepository()
+        self.variant_repository = variant_repository or VariantRepository()
+        self.change_repository = change_repository or VariantChangeRepository()
+
+    async def list_releases(
+        self,
+        experiment_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[ReleaseRead]:
+        params: dict[str, Any] | None = None
+        if experiment_id:
+            params = {"filter[experiment_id][_eq]": experiment_id}
+
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [release_to_read_model(to_release(item)) for item in items]
+
+    async def get_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseRead | None:
+        item = await self.repository.get(release_id, access_token=access_token)
+        if not item:
+            return None
+        return release_to_read_model(to_release(item))
+
+    async def build_release(
+        self,
+        payload: BuildReleaseRequest,
+        access_token: str | None = None,
+    ) -> ReleaseRead:
+        experiment_id = payload.experiment_id
+
+        # Fetch all variants for the experiment
+        variant_items = await self.variant_repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id},
+            access_token=access_token,
+        )
+
+        # Build per-variant runtime payloads
+        variants_payload: list[dict[str, Any]] = []
+        for variant_item in variant_items:
+            variant_id = str(variant_item["id"])
+            change_items = await self.change_repository.list(
+                params={"filter[variant_id][_eq]": variant_id},
+                access_token=access_token,
+            )
+            changes = [
+                VariantChange(
+                    id=str(c["id"]),
+                    variant_id=variant_id,
+                    change_type=str(c.get("change_type", "")),
+                    selector_type=str(c.get("selector_type", "")),
+                    selector_value=str(c.get("selector_value", "")),
+                    sort_order=int(c.get("sort_order", 0)),
+                    payload=c.get("payload"),
+                )
+                for c in change_items
+            ]
+            runtime_payload = build_runtime_payload_from_changes(variant_id, changes)
+            variants_payload.append({
+                "variant_id": variant_id,
+                "variant_key": str(variant_item.get("variant_key", "")),
+                "traffic_weight": int(variant_item.get("traffic_weight", 0)),
+                "operations": [asdict(op) for op in runtime_payload.operations],
+            })
+
+        # Determine next version_no
+        existing = await self.repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id, "sort": "-version_no", "limit": "1"},
+            access_token=access_token,
+        )
+        next_version = (int(existing[0]["version_no"]) + 1) if existing else 1
+
+        new_release = await self.repository.create(
+            {
+                "experiment_id": experiment_id,
+                "version_no": next_version,
+                "status": "draft",
+                "runtime_payload": {"variants": variants_payload},
+            },
+            access_token=access_token,
+        )
+        return release_to_read_model(to_release(new_release))
+
+    async def publish_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        # Fetch the target release to get experiment_id
+        target = await self.repository.get(release_id, access_token=access_token)
+        if not target:
+            return None
+
+        experiment_id = str(target["experiment_id"])
+
+        # Demote any currently published release in this experiment to draft
+        currently_published = await self.repository.list(
+            params={
+                "filter[experiment_id][_eq]": experiment_id,
+                "filter[status][_eq]": "published",
+            },
+            access_token=access_token,
+        )
+        for other in currently_published:
+            if str(other["id"]) != release_id:
+                await self.repository.update(str(other["id"]), {"status": "draft"}, access_token=access_token)
+
+        item = await self.repository.update(release_id, {"status": "published"}, access_token=access_token)
+        if not item:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(item["id"]),
+            status=str(item["status"]),
+            version_no=int(item["version_no"]),
+        )
+
+    async def rollback_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        # Fetch the target release to get experiment_id and version_no
+        target = await self.repository.get(release_id, access_token=access_token)
+        if not target:
+            return None
+
+        experiment_id = str(target["experiment_id"])
+        current_version_no = int(target["version_no"])
+
+        # Demote the current release back to draft
+        await self.repository.update(release_id, {"status": "draft"}, access_token=access_token)
+
+        # Find the most recent draft release with an earlier version_no to restore
+        previous_candidates = await self.repository.list(
+            params={
+                "filter[experiment_id][_eq]": experiment_id,
+                "filter[status][_eq]": "draft",
+                "filter[version_no][_lt]": str(current_version_no),
+                "sort": "-version_no",
+                "limit": "1",
+            },
+            access_token=access_token,
+        )
+
+        if previous_candidates:
+            restored = await self.repository.update(
+                str(previous_candidates[0]["id"]),
+                {"status": "published"},
+                access_token=access_token,
+            )
+            if restored:
+                return ReleaseLifecycleResponse(
+                    id=str(restored["id"]),
+                    status=str(restored["status"]),
+                    version_no=int(restored["version_no"]),
+                )
+
+        # No previous release to restore — return the now-drafted current release
+        updated = await self.repository.get(release_id, access_token=access_token)
+        if not updated:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(updated["id"]),
+            status=str(updated["status"]),
+            version_no=int(updated["version_no"]),
+        )
+
+    async def archive_release(
+        self,
+        release_id: str,
+        access_token: str | None = None,
+    ) -> ReleaseLifecycleResponse | None:
+        item = await self.repository.update(release_id, {"status": "archived"}, access_token=access_token)
+        if not item:
+            return None
+        return ReleaseLifecycleResponse(
+            id=str(item["id"]),
+            status=str(item["status"]),
+            version_no=int(item["version_no"]),
+        )

backend/app/application/admin/sdk_configs.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from app.domain.mappers import to_sdk_config
+from app.repositories.directus.sdk_configs import SdkConfigRepository
+from app.schemas.admin import SdkConfigRead, sdk_config_to_read_model
+
+
+class SdkConfigService:
+    """Application service for SDK config management."""
+
+    def __init__(self, repository: SdkConfigRepository | None = None) -> None:
+        self.repository = repository or SdkConfigRepository()
+
+    async def list_sdk_configs(self, access_token: str | None = None) -> list[SdkConfigRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [sdk_config_to_read_model(to_sdk_config(item)) for item in items]
+
+    async def get_sdk_config(
+        self,
+        sdk_config_id: str,
+        access_token: str | None = None,
+    ) -> SdkConfigRead | None:
+        item = await self.repository.get(sdk_config_id, access_token=access_token)
+        if not item:
+            return None
+        return sdk_config_to_read_model(to_sdk_config(item))

backend/app/application/admin/sites.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from app.domain.mappers import to_site
+from app.repositories.directus.sites import SiteRepository
+from app.schemas.admin import SiteRead, site_to_read_model
+
+
+class SiteService:
+    """Application service for site administration.
+
+    Site is a good example of a content-like resource:
+    FastAPI owns orchestration, while Directus remains the audited store.
+    """
+
+    def __init__(self, repository: SiteRepository | None = None) -> None:
+        self.repository = repository or SiteRepository()
+
+    async def list_sites(self, access_token: str | None = None) -> list[SiteRead]:
+        items = await self.repository.list(access_token=access_token)
+        return [site_to_read_model(to_site(item)) for item in items]
+
+    async def get_site(
+        self,
+        site_id: str,
+        access_token: str | None = None,
+    ) -> SiteRead | None:
+        item = await self.repository.get(site_id, access_token=access_token)
+        if not item:
+            return None
+        return site_to_read_model(to_site(item))

backend/app/application/admin/variants.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException
+
+from app.domain.keys import generate_variant_key
+from app.domain.mappers import to_variant
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.admin import VariantCreate, VariantRead, VariantUpdate, variant_to_read_model
+
+
+class VariantService:
+    """Application service for variant management."""
+
+    def __init__(self, repository: VariantRepository | None = None) -> None:
+        self.repository = repository or VariantRepository()
+
+    async def _assert_weights_sum_100(
+        self,
+        experiment_id: str,
+        new_weight: int,
+        exclude_variant_id: str | None = None,
+        access_token: str | None = None,
+    ) -> None:
+        items = await self.repository.list(
+            params={"filter[experiment_id][_eq]": experiment_id},
+            access_token=access_token,
+        )
+        existing_sum = sum(
+            int(item.get("traffic_weight", 0))
+            for item in items
+            if str(item["id"]) != exclude_variant_id
+        )
+        if existing_sum + new_weight != 100:
+            raise HTTPException(
+                status_code=400,
+                detail=f"所有變體的流量權重加總必須等於 100（目前其他變體合計 {existing_sum}，本次輸入 {new_weight}）",
+            )
+
+    async def list_variants(
+        self,
+        experiment_id: str | None = None,
+        access_token: str | None = None,
+    ) -> list[VariantRead]:
+        params: dict[str, Any] | None = None
+        if experiment_id:
+            params = {"filter[experiment_id][_eq]": experiment_id}
+
+        items = await self.repository.list(params=params, access_token=access_token)
+        return [variant_to_read_model(to_variant(item)) for item in items]
+
+    async def get_variant(
+        self,
+        variant_id: str,
+        access_token: str | None = None,
+    ) -> VariantRead | None:
+        item = await self.repository.get(variant_id, access_token=access_token)
+        if not item:
+            return None
+        return variant_to_read_model(to_variant(item))
+
+    async def create_variant(
+        self,
+        payload: VariantCreate,
+        access_token: str | None = None,
+    ) -> VariantRead:
+        await self._assert_weights_sum_100(
+            experiment_id=payload.experiment_id,
+            new_weight=payload.traffic_weight,
+            access_token=access_token,
+        )
+        data: dict[str, Any] = payload.model_dump(exclude_none=True)
+        data["variant_key"] = generate_variant_key()
+        item = await self.repository.create(data, access_token=access_token)
+        return variant_to_read_model(to_variant(item))
+
+    async def update_variant(
+        self,
+        variant_id: str,
+        payload: VariantUpdate,
+        access_token: str | None = None,
+    ) -> VariantRead | None:
+        data: dict[str, Any] = payload.model_dump(exclude_unset=True)
+        if "traffic_weight" in data:
+            existing = await self.repository.get(variant_id, access_token=access_token)
+            if existing:
+                await self._assert_weights_sum_100(
+                    experiment_id=str(existing["experiment_id"]),
+                    new_weight=data["traffic_weight"],
+                    exclude_variant_id=variant_id,
+                    access_token=access_token,
+                )
+        item = await self.repository.update(variant_id, data, access_token=access_token)
+        if not item:
+            return None
+        return variant_to_read_model(to_variant(item))

backend/app/application/auth/__init__.py

@@ -0,0 +1,2 @@
+"""Authentication and user-context services."""
+

backend/app/application/auth/context.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+
+from fastapi import HTTPException, status
+
+from app.domain.permissions import build_permission_context
+from app.repositories.directus.client import DirectusClient
+from app.schemas.auth import AuthenticatedUser, PermissionContextRead
+
+
+class AuthContextService:
+    """Validates Directus-issued tokens and normalizes user context.
+
+    FastAPI remains the formal API entrypoint, but Directus is still the source
+    of truth for login/session/role data. This service is the seam between them.
+    """
+
+    # Keep the first auth bootstrap intentionally conservative.
+    # Directus `/users/me` on this project reliably returns the core user/role
+    # fields below, while deeper `user_group.*` expansions can collapse the
+    # payload back to only `{id}`. We can layer group/domain permissions back in
+    # later once the base admin flow is verified end to end.
+    me_fields = [
+        "email",
+        "first_name",
+        "id",
+        "role.id",
+        "role.name",
+        "status",
+    ]
+
+    def __init__(self, client: DirectusClient | None = None) -> None:
+        self.client = client or DirectusClient()
+
+    async def get_authenticated_user(self, access_token: str) -> AuthenticatedUser:
+        if not access_token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Missing access token.",
+            )
+
+        me = await self.client.get_current_user(
+            access_token=access_token,
+            fields=self.me_fields,
+        )
+        if not me:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Unable to resolve current user from Directus.",
+            )
+
+        user_group = me.get("user_group") or {}
+        permissions = user_group.get("domain_permissions") or []
+        normalized_permissions = [str(permission) for permission in permissions]
+        role = me.get("role") or {}
+        permission_context = build_permission_context(
+            role_name=role.get("name"),
+            domain_permissions=normalized_permissions,
+        )
+
+        # Keep the normalized payload explicit so downstream services do not need
+        # to know the exact nested Directus response shape.
+        return AuthenticatedUser.model_validate(
+            {
+                **me,
+                "domain_permissions": normalized_permissions,
+                "permissions": PermissionContextRead.model_validate(asdict(permission_context)),
+            }
+        )

backend/app/application/editor/__init__.py

@@ -0,0 +1,2 @@
+"""Editor services and builders."""
+

backend/app/application/editor/service.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from app.domain.editor import EditorSession, VariantChange
+from app.domain.editor_builder import build_runtime_payload_from_changes
+from app.repositories.directus.variant_changes import VariantChangeRepository
+from app.repositories.native.editor_sessions import EditorSessionRepository
+from app.schemas.auth import AuthenticatedUser
+from app.schemas.editor import (
+    BuildPreviewRequest,
+    BuildPreviewResponse,
+    EditorChangeListResponse,
+    EditorChangeRead,
+    EditorSessionCreateRequest,
+    EditorSessionRead,
+    EditorSessionUpdateRequest,
+    SaveVariantChangesRequest,
+)
+
+
+class EditorService:
+    """Application service for visual-editor workflows."""
+
+    def __init__(
+        self,
+        change_repository: VariantChangeRepository | None = None,
+        session_repository: EditorSessionRepository | None = None,
+    ) -> None:
+        self.change_repository = change_repository or VariantChangeRepository()
+        self.session_repository = session_repository or EditorSessionRepository()
+
+    async def create_session(
+        self,
+        request: EditorSessionCreateRequest,
+        current_user: AuthenticatedUser,
+    ) -> EditorSessionRead:
+        session = EditorSession(
+            variant_id=request.variant_id,
+            mode=request.mode,
+            base_url=request.base_url,
+            actor_id=current_user.id,
+            actor_email=current_user.email,
+        )
+        await self.session_repository.create(session)
+        return EditorSessionRead.model_validate(asdict(session))
+
+    async def get_session(self, session_id: str) -> EditorSessionRead | None:
+        session = await self.session_repository.get(session_id)
+        if not session:
+            return None
+        return EditorSessionRead.model_validate(asdict(session))
+
+    async def update_session(
+        self,
+        session_id: str,
+        request: EditorSessionUpdateRequest,
+    ) -> EditorSessionRead | None:
+        session = await self.session_repository.get(session_id)
+        if not session:
+            return None
+
+        if request.status is not None:
+            session.status = request.status
+        if request.draft_changes is not None:
+            session.draft_changes = request.draft_changes
+        session.updated_at = datetime.now(timezone.utc)
+
+        await self.session_repository.update(session)
+        return EditorSessionRead.model_validate(asdict(session))
+
+    async def delete_session(self, session_id: str) -> None:
+        await self.session_repository.delete(session_id)
+
+    async def list_changes(self, variant_id: str) -> EditorChangeListResponse:
+        items = await self.change_repository.list(params={"filter[variant_id][_eq]": variant_id})
+        mapped = [EditorChangeRead.model_validate(item) for item in items]
+        return EditorChangeListResponse(items=mapped)
+
+    async def list_changes_with_access_token(
+        self,
+        variant_id: str,
+        access_token: str,
+    ) -> EditorChangeListResponse:
+        items = await self.change_repository.list(
+            params={"filter[variant_id][_eq]": variant_id},
+            access_token=access_token,
+        )
+        mapped = [EditorChangeRead.model_validate(item) for item in items]
+        return EditorChangeListResponse(items=mapped)
+
+    async def save_changes(
+        self,
+        variant_id: str,
+        request: SaveVariantChangesRequest,
+    ) -> EditorChangeListResponse:
+        # Full-replace semantics: delete any existing changes not present in the request.
+        existing = await self.change_repository.list(params={"filter[variant_id][_eq]": variant_id})
+        incoming_ids = {item.id for item in request.items if item.id}
+        for existing_item in existing:
+            if str(existing_item["id"]) not in incoming_ids:
+                await self.change_repository.delete(str(existing_item["id"]))
+
+        saved_items: list[EditorChangeRead] = []
+        for item in request.items:
+            payload = item.model_dump()
+            payload["variant_id"] = variant_id
+
+            change_id = payload.pop("id", None)
+            if change_id:
+                saved = await self.change_repository.update(change_id, payload)
+            else:
+                payload["id"] = str(uuid4())
+                saved = await self.change_repository.create(payload)
+
+            saved_items.append(EditorChangeRead.model_validate(saved))
+
+        return EditorChangeListResponse(items=saved_items)
+
+    async def save_changes_with_access_token(
+        self,
+        variant_id: str,
+        request: SaveVariantChangesRequest,
+        access_token: str,
+    ) -> EditorChangeListResponse:
+        # Full-replace semantics: delete any existing changes not present in the request.
+        existing = await self.change_repository.list(
+            params={"filter[variant_id][_eq]": variant_id},
+            access_token=access_token,
+        )
+        incoming_ids = {item.id for item in request.items if item.id}
+        for existing_item in existing:
+            if str(existing_item["id"]) not in incoming_ids:
+                await self.change_repository.delete(str(existing_item["id"]), access_token=access_token)
+
+        saved_items: list[EditorChangeRead] = []
+        for item in request.items:
+            payload = item.model_dump()
+            payload["variant_id"] = variant_id
+
+            change_id = payload.pop("id", None)
+            if change_id:
+                saved = await self.change_repository.update(change_id, payload, access_token=access_token)
+            else:
+                payload["id"] = str(uuid4())
+                saved = await self.change_repository.create(payload, access_token=access_token)
+
+            saved_items.append(EditorChangeRead.model_validate(saved))
+
+        return EditorChangeListResponse(items=saved_items)
+
+    async def build_preview(self, request: BuildPreviewRequest) -> BuildPreviewResponse:
+        changes = [
+            VariantChange(
+                id=item.id or str(uuid4()),
+                variant_id=request.variant_id,
+                change_type=item.change_type,
+                selector_type=item.selector_type,
+                selector_value=item.selector_value,
+                sort_order=item.sort_order,
+                payload=item.payload,
+            )
+            for item in request.items
+        ]
+        preview = build_runtime_payload_from_changes(request.variant_id, changes)
+        return BuildPreviewResponse(
+            variant_id=preview.variant_id,
+            generated_at=preview.generated_at,
+            operations=[asdict(operation) for operation in preview.operations],
+        )

backend/app/application/observability/__init__.py

@@ -0,0 +1,2 @@
+"""Audit and telemetry services."""
+

backend/app/application/observability/service.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from app.domain.observability import AuditLogEntry, SystemEvent
+from app.repositories.native.audit_logs import AuditLogRepository
+from app.repositories.native.system_events import SystemEventRepository
+
+
+class ObservabilityService:
+    """Facade for audit and telemetry writes.
+
+    Keeping this behind one service lets us fan out later to:
+    - native PostgreSQL tables
+    - queue/stream pipelines
+    - external monitoring sinks
+    without changing runtime/admin services.
+    """
+
+    def __init__(
+        self,
+        audit_repository: AuditLogRepository | None = None,
+        system_event_repository: SystemEventRepository | None = None,
+    ) -> None:
+        self.audit_repository = audit_repository or AuditLogRepository()
+        self.system_event_repository = system_event_repository or SystemEventRepository()
+
+    async def record_audit(self, entry: AuditLogEntry) -> AuditLogEntry:
+        return await self.audit_repository.add(entry)
+
+    async def record_system_event(self, event: SystemEvent) -> SystemEvent:
+        return await self.system_event_repository.add(event)
+

backend/app/application/runtime/__init__.py

@@ -0,0 +1,2 @@
+"""Runtime services used by the SDK-facing API."""
+

backend/app/application/runtime/assignment.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from app.application.observability.service import ObservabilityService
+from app.domain.mappers import to_experiment, to_release, to_site, to_variant
+from app.domain.observability import SystemEvent
+from app.domain.runtime import RuntimeExperimentContext, RuntimeVariantCandidate, choose_variant
+from app.repositories.directus.experiments import ExperimentRepository
+from app.repositories.directus.releases import ReleaseRepository
+from app.repositories.directus.sites import SiteRepository
+from app.repositories.directus.variants import VariantRepository
+from app.schemas.runtime import (
+    RuntimeAssignRequest,
+    RuntimeAssignResponse,
+    RuntimeBootstrapRequest,
+    RuntimeBootstrapResponse,
+    RuntimeExperimentInput,
+    RuntimeEventRequest,
+    RuntimeEventResponse,
+    RuntimePayloadRequest,
+    RuntimePayloadResponse,
+    RuntimeVariantCandidateInput,
+)
+
+
+class RuntimeService:
+    """First-pass runtime orchestration service.
+
+    The current version focuses on:
+    - deterministic assignment rules
+    - stable API contracts for the SDK
+    - keeping runtime logic out of the frontend
+
+    Later we can swap the input source from request payloads to repositories
+    without changing the external response shapes.
+    """
+
+    def __init__(
+        self,
+        observability: ObservabilityService | None = None,
+        site_repository: SiteRepository | None = None,
+        experiment_repository: ExperimentRepository | None = None,
+        variant_repository: VariantRepository | None = None,
+        release_repository: ReleaseRepository | None = None,
+    ) -> None:
+        self.observability = observability or ObservabilityService()
+        self.site_repository = site_repository or SiteRepository()
+        self.experiment_repository = experiment_repository or ExperimentRepository()
+        self.variant_repository = variant_repository or VariantRepository()
+        self.release_repository = release_repository or ReleaseRepository()
+
+    async def bootstrap(self, request: RuntimeBootstrapRequest) -> RuntimeBootstrapResponse:
+        site = await self._resolve_site(request.site_id, request.site_key)
+        if not site:
+            return RuntimeBootstrapResponse(
+                site_id=request.site_id,
+                site_key=request.site_key,
+                url=request.url,
+                visitor_id=request.visitor_id,
+                candidate_experiments=[],
+            )
+
+        experiments = await self.experiment_repository.list(
+            params={
+                "filter[site_id][_eq]": site.id,
+                "filter[status][_eq]": "running",
+            }
+        )
+
+        candidate_experiments = []
+        for raw_experiment in experiments:
+            experiment = to_experiment(raw_experiment)
+            if not self._matches_targeting(request.url, request.user_agent, experiment.targeting_config):
+                continue
+
+            raw_releases = await self.release_repository.list(
+                params={
+                    "filter[experiment_id][_eq]": experiment.id,
+                    "filter[status][_eq]": "published",
+                    "sort[]": "-version_no",
+                    "limit": 1,
+                }
+            )
+            release = to_release(raw_releases[0]) if raw_releases else None
+
+            # Build a traffic weight index from the release snapshot when available.
+            # This ensures assignment weights are stable and match what was published,
+            # even if variant weights have since been edited.
+            snapshot_weight: dict[str, int] = {}
+            snapshot_key: dict[str, str] = {}
+            if release and isinstance(release.runtime_payload, dict):
+                for sv in release.runtime_payload.get("variants", []):
+                    vid = str(sv.get("variant_id", ""))
+                    if vid:
+                        snapshot_weight[vid] = int(sv.get("traffic_weight", 0))
+                        snapshot_key[vid] = str(sv.get("variant_key", ""))
+
+            raw_variants = await self.variant_repository.list(
+                params={"filter[experiment_id][_eq]": experiment.id}
+            )
+            variants = [to_variant(item) for item in raw_variants]
+            if not variants:
+                continue
+
+            candidate_experiments.append(
+                RuntimeExperimentInput(
+                    experiment_id=experiment.id,
+                    experiment_key=experiment.experiment_key,
+                    status=experiment.status,
+                    site_key=site.site_key,
+                    release_id=release.id if release else None,
+                    release_version=release.version_no if release else None,
+                    payload=release.runtime_payload if release else None,
+                    variants=[
+                        RuntimeVariantCandidateInput(
+                            id=variant.id,
+                            variant_key=snapshot_key.get(variant.id, variant.variant_key),
+                            traffic_weight=snapshot_weight.get(variant.id, variant.traffic_weight),
+                            content_config=variant.content_config,
+                        )
+                        for variant in variants
+                    ],
+                )
+            )
+
+        return RuntimeBootstrapResponse(
+            site_id=site.id,
+            site_key=site.site_key,
+            url=request.url,
+            visitor_id=request.visitor_id,
+            candidate_experiments=candidate_experiments,
+        )
+
+    async def assign(self, request: RuntimeAssignRequest) -> RuntimeAssignResponse | None:
+        experiment = RuntimeExperimentContext(
+            experiment_id=request.experiment.experiment_id,
+            experiment_key=request.experiment.experiment_key,
+            status=request.experiment.status,
+            site_key=request.experiment.site_key,
+            assignment_salt=request.experiment.assignment_salt,
+            release_id=request.experiment.release_id,
+            release_version=request.experiment.release_version,
+            payload=request.experiment.payload,
+            variants=[
+                RuntimeVariantCandidate(
+                    id=variant.id,
+                    variant_key=variant.variant_key,
+                    traffic_weight=variant.traffic_weight,
+                    content_config=variant.content_config,
+                )
+                for variant in request.experiment.variants
+            ],
+        )
+
+        decision = choose_variant(
+            experiment_id=experiment.experiment_id,
+            experiment_key=experiment.experiment_key,
+            visitor_id=request.visitor_id,
+            site_key=experiment.site_key,
+            assignment_salt=experiment.assignment_salt,
+            variants=experiment.variants,
+        )
+        if not decision:
+            return None
+
+        await self.observability.record_system_event(
+            SystemEvent(
+                category="runtime_assignment",
+                event_name="assignment_decided",
+                experiment_id=decision.experiment_id,
+                experiment_key=decision.experiment_key,
+                variant_id=decision.variant_id,
+                variant_key=decision.variant_key,
+                visitor_id=request.visitor_id,
+                payload={"bucket": decision.bucket, "reason": decision.reason},
+            )
+        )
+
+        return RuntimeAssignResponse(
+            experiment_id=decision.experiment_id,
+            experiment_key=decision.experiment_key,
+            variant_id=decision.variant_id,
+            variant_key=decision.variant_key,
+            bucket=decision.bucket,
+            reason=decision.reason,
+        )
+
+    async def payload(self, request: RuntimePayloadRequest) -> RuntimePayloadResponse:
+        assignment = await self.assign(
+            RuntimeAssignRequest(
+                visitor_id=request.visitor_id,
+                experiment=request.experiment,
+            )
+        )
+
+        return RuntimePayloadResponse(
+            experiment_id=request.experiment.experiment_id,
+            experiment_key=request.experiment.experiment_key,
+            release_id=request.experiment.release_id,
+            release_version=request.experiment.release_version,
+            assigned_variant_id=assignment.variant_id if assignment else None,
+            assigned_variant_key=assignment.variant_key if assignment else None,
+            payload=request.experiment.payload,
+        )
+
+    async def ingest_event(self, request: RuntimeEventRequest) -> RuntimeEventResponse:
+        # Event forwarding/queueing will be introduced when GA4/GTM ingest and
+        # audit storage are wired in. We preserve the external contract now.
+        await self.observability.record_system_event(
+            SystemEvent(
+                category="runtime_event",
+                event_name=request.event_name,
+                site_id=request.site_id,
+                site_key=request.site_key,
+                experiment_id=request.experiment_id,
+                experiment_key=request.experiment_key,
+                variant_id=request.variant_id,
+                variant_key=request.variant_key,
+                visitor_id=request.visitor_id,
+                payload=request.payload,
+            )
+        )
+        return RuntimeEventResponse(
+            accepted=True,
+            event_name=request.event_name,
+        )
+
+    async def _resolve_site(self, site_id: str | None, site_key: str | None):
+        if site_id:
+            item = await self.site_repository.get(site_id)
+            if item:
+                return to_site(item)
+
+        if site_key:
+            items = await self.site_repository.list(
+                params={"filter[site_key][_eq]": site_key}
+            )
+            if items:
+                return to_site(items[0])
+
+        return None
+
+    def _matches_targeting(
+        self,
+        request_url: str,
+        user_agent: str | None,
+        targeting_config: dict[str, Any] | list[Any] | None,
+    ) -> bool:
+        if not isinstance(targeting_config, dict):
+            return True
+
+        # Device targeting — empty list = all devices
+        device_targets = targeting_config.get("device_targets")
+        if device_targets:
+            detected = self._detect_device(user_agent or "")
+            if detected not in device_targets:
+                return False
+
+        # URL rules (all must match — AND logic)
+        url_rules = targeting_config.get("url_rules")
+        if url_rules:
+            return all(self._matches_url_rule(request_url, rule) for rule in url_rules)
+
+        # Fallback: base_url prefix check
+        base_url = targeting_config.get("base_url")
+        if base_url:
+            return str(request_url).startswith(str(base_url))
+
+        return True
+
+    def _detect_device(self, user_agent: str) -> str:
+        ua = user_agent.lower()
+        if "ipad" in ua or ("android" in ua and "mobile" not in ua):
+            return "tablet"
+        if "mobile" in ua or "iphone" in ua or "android" in ua:
+            return "mobile"
+        return "desktop"
+
+    def _matches_url_rule(self, url: str, rule: dict[str, Any]) -> bool:
+        operator = rule.get("operator", "contains")
+        value = str(rule.get("value", ""))
+        if not value:
+            return True
+        if operator == "contains":
+            return value in url
+        if operator == "equals":
+            return url == value
+        if operator == "starts_with":
+            return url.startswith(value)
+        if operator == "regex":
+            try:
+                return bool(re.search(value, url))
+            except re.error:
+                return False
+        return True