refactor(backend): group runtime services

BugMaker-Boyan · BugMaker-Boyan · commit 5d4e79753d2a · 2026-05-04T13:38:22.000Z
diff --git a/packages/backend/app/api/v1/chat.py b/packages/backend/app/api/v1/chat.py
@@ -16,7 +16,7 @@
 from app.repositories import SessionRepository
 from app.schemas import ChatRequest, SSEMessage
 from app.services import get_or_create_session, start_agent_workflow
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
 
 router = APIRouter(prefix="/chat", tags=["chat"])
 
diff --git a/packages/backend/app/api/v1/sessions.py b/packages/backend/app/api/v1/sessions.py
@@ -27,7 +27,7 @@
     WorkflowQueuedRunResponse,
 )
 from app.sandbox import sandbox_manager
-from app.services.preview_runtime_manager import preview_runtime_manager
+from app.runtime.services.preview_manager import preview_runtime_manager
 from app.services import attach_datasource_to_session, detach_datasource_from_session, list_session_attachments
 from app.workflow.services.file_service import (
     prepare_tracked_workflow_draft_run,
diff --git a/packages/backend/app/api/v1/system.py b/packages/backend/app/api/v1/system.py
@@ -6,7 +6,7 @@
 from pydantic import BaseModel
 
 from app.core.config import settings
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
 
 router = APIRouter(prefix="/system", tags=["system"])
 
diff --git a/packages/backend/app/api/v1/workflows.py b/packages/backend/app/api/v1/workflows.py
@@ -14,7 +14,7 @@
 from app.models.workflow_run import WorkflowRun
 from app.repositories import WorkflowRepository, WorkflowRunRepository
 from app.schemas.workflow import WorkflowCreate, WorkflowResponse, WorkflowRunResponse, WorkflowUpdate
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
 from app.tasks.workflow_tasks import run_workflow_task
 from app.core.config import settings
 
diff --git a/packages/backend/app/runtime/__init__.py b/packages/backend/app/runtime/__init__.py
@@ -0,0 +1 @@
+"""Runtime infrastructure package."""
diff --git a/packages/backend/app/runtime/services/__init__.py b/packages/backend/app/runtime/services/__init__.py
@@ -0,0 +1 @@
+"""Runtime service helpers."""
diff --git a/packages/backend/app/runtime/services/metrics.py b/packages/backend/app/runtime/services/metrics.py
diff --git a/packages/backend/app/runtime/services/preview.py b/packages/backend/app/runtime/services/preview.py
diff --git a/packages/backend/app/runtime/services/preview_manager.py b/packages/backend/app/runtime/services/preview_manager.py
@@ -5,8 +5,8 @@
 import docker
 
 from app.core.config import settings
+from app.runtime.services.preview import preview_containers_to_cleanup
 from app.services.docker_control_client import get_docker_control_client
-from app.services.preview_runtime import preview_containers_to_cleanup
 from deepeye.utils.logger import logger
 
 
diff --git a/packages/backend/app/runtime_control/main.py b/packages/backend/app/runtime_control/main.py
@@ -12,7 +12,7 @@
 from app.core.config import settings
 from app.sandbox import sandbox_manager
 from app.services.dashboard_deploy_service import dashboard_deployer
-from app.services.preview_runtime_manager import preview_runtime_manager
+from app.runtime.services.preview_manager import preview_runtime_manager
 from app.services.video_deploy_service import video_deployer
 
 
diff --git a/packages/backend/app/sandbox/docker_sandbox.py b/packages/backend/app/sandbox/docker_sandbox.py
@@ -17,8 +17,8 @@
 from app.core.config import settings
 from app.services.docker_build_paths import resolve_docker_build_target
 from app.services.docker_control_client import get_docker_control_client
-from app.services.runtime_metrics import runtime_metrics
-from deepeye.sandbox import CommandResult, SandboxProtocol
+from app.runtime.services.metrics import runtime_metrics
+from deepeye.sandbox import CommandResult
 from deepeye.utils.logger import logger
 
 
diff --git a/packages/backend/app/services/dashboard_deploy_service.py b/packages/backend/app/services/dashboard_deploy_service.py
@@ -15,8 +15,8 @@
 from app.core.config import settings
 from app.services.docker_control_client import get_docker_control_client
 from app.services.docker_build_paths import resolve_docker_build_target
-from app.services.preview_runtime import preview_container_labels, preview_containers_to_cleanup
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
+from app.runtime.services.preview import preview_container_labels, preview_containers_to_cleanup
 from deepeye.utils.logger import logger
 
 
diff --git a/packages/backend/app/services/video_deploy_service.py b/packages/backend/app/services/video_deploy_service.py
@@ -36,8 +36,8 @@
 from app.core.config import get_video_session_root, settings
 from app.services.docker_control_client import get_docker_control_client
 from app.services.docker_build_paths import resolve_docker_build_target
-from app.services.preview_runtime import preview_container_labels, preview_containers_to_cleanup
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
+from app.runtime.services.preview import preview_container_labels, preview_containers_to_cleanup
 from app.services.video_component_naming import expected_scene_component_files
 from deepeye.utils.logger import logger
 
diff --git a/packages/backend/app/test/test_architecture_boundaries.py b/packages/backend/app/test/test_architecture_boundaries.py
@@ -9,6 +9,7 @@
 APP_DIR = Path(__file__).resolve().parents[1]
 SERVICES_DIR = APP_DIR / "services"
 DATASOURCE_DIR = APP_DIR / "datasource"
+RUNTIME_DIR = APP_DIR / "runtime"
 WORKFLOW_DIR = APP_DIR / "workflow"
 LEGACY_DATASOURCE_SERVICE_MODULES = {
     "app.services.datasource_connection_service",
@@ -36,6 +37,11 @@
     "app.services.workflow_tracking_service",
     "app.services.workflow_workspace_state",
 }
+LEGACY_RUNTIME_SERVICE_MODULES = {
+    "app.services.preview_runtime",
+    "app.services.preview_runtime_manager",
+    "app.services.runtime_metrics",
+}
 
 
 def _imported_modules(path: Path) -> set[str]:
@@ -86,6 +92,18 @@ def test_datasource_domain_does_not_depend_on_tools_layer() -> None:
     assert violations == []
 
 
+def test_runtime_domain_does_not_depend_on_tools_layer() -> None:
+    violations: list[str] = []
+    for path in sorted(RUNTIME_DIR.rglob("*.py")):
+        if path.name == "__init__.py":
+            continue
+        for module in sorted(_imported_modules(path)):
+            if module == "app.tools" or module.startswith("app.tools."):
+                violations.append(f"{path.relative_to(APP_DIR)} imports {module}")
+
+    assert violations == []
+
+
 def test_services_root_does_not_contain_workflow_modules() -> None:
     workflow_modules = sorted(path.name for path in SERVICES_DIR.glob("workflow_*.py"))
 
@@ -98,6 +116,16 @@ def test_services_root_does_not_contain_datasource_modules() -> None:
     assert datasource_modules == []
 
 
+def test_services_root_does_not_contain_runtime_modules() -> None:
+    runtime_modules = sorted(
+        path.name
+        for pattern in ("preview_runtime*.py", "runtime_metrics.py")
+        for path in SERVICES_DIR.glob(pattern)
+    )
+
+    assert runtime_modules == []
+
+
 def test_moved_datasource_services_use_domain_import_paths() -> None:
     violations: list[str] = []
     for path in sorted(APP_DIR.rglob("*.py")):
@@ -108,6 +136,16 @@ def test_moved_datasource_services_use_domain_import_paths() -> None:
     assert violations == []
 
 
+def test_moved_runtime_services_use_domain_import_paths() -> None:
+    violations: list[str] = []
+    for path in sorted(APP_DIR.rglob("*.py")):
+        legacy_imports = sorted(_imported_modules(path) & LEGACY_RUNTIME_SERVICE_MODULES)
+        for module in legacy_imports:
+            violations.append(f"{path.relative_to(APP_DIR)} imports {module}")
+
+    assert violations == []
+
+
 def test_moved_workflow_services_use_domain_import_paths() -> None:
     violations: list[str] = []
     for path in sorted(APP_DIR.rglob("*.py")):
diff --git a/packages/backend/app/test/test_preview_runtime.py b/packages/backend/app/test/test_preview_runtime.py
@@ -9,7 +9,7 @@
 os.environ.setdefault("LLM_BASE_URL", "http://localhost:8000")
 os.environ.setdefault("LLM_MODEL", "test-model")
 
-from app.services.preview_runtime import preview_container_labels, preview_containers_to_cleanup
+from app.runtime.services.preview import preview_container_labels, preview_containers_to_cleanup
 
 
 def _container(name: str, *, status: str, created_at_epoch: int):
diff --git a/packages/backend/app/test/test_preview_runtime_manager.py b/packages/backend/app/test/test_preview_runtime_manager.py
@@ -7,7 +7,7 @@
 os.environ.setdefault("LLM_BASE_URL", "http://localhost:8000")
 os.environ.setdefault("LLM_MODEL", "test-model")
 
-from app.services import preview_runtime_manager as preview_runtime_manager_module
+from app.runtime.services import preview_manager as preview_runtime_manager_module
 
 
 class _FakeContainer:
diff --git a/packages/backend/app/test/test_runtime_metrics.py b/packages/backend/app/test/test_runtime_metrics.py
@@ -6,7 +6,7 @@
 os.environ.setdefault("LLM_MODEL", "test-model")
 
 from app.api.v1.system import get_runtime_summary
-from app.services.runtime_metrics import runtime_metrics
+from app.runtime.services.metrics import runtime_metrics
 
 
 def test_runtime_metrics_snapshot_and_summary_endpoint() -> None:

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@`
`27`	`27`	`WorkflowQueuedRunResponse,`
`28`	`28`	`)`
`29`	`29`	`from app.sandbox import sandbox_manager`
`30`		`-from app.services.preview_runtime_manager import preview_runtime_manager`
	`30`	`+from app.runtime.services.preview_manager import preview_runtime_manager`
`31`	`31`	`from app.services import attach_datasource_to_session, detach_datasource_from_session, list_session_attachments`
`32`	`32`	`from app.workflow.services.file_service import (`
`33`	`33`	`prepare_tracked_workflow_draft_run,`