Backend Architecture Guide

Current Runtime Layout

src/apis/: FastAPI routers and API-facing contracts.
src/core/: orchestration and domain-heavy services.
src/memory/: persistence/retrieval repositories and clients.
src/common/, src/configs/, src/utils/: shared models, config, and utility layers.

Keep routers thin: validate input, call service, return response model.
Move business logic into domain services under src/core/<domain>/.
Keep persistence access in repositories (src/memory/repositories/*) and avoid DB calls directly inside routers.
Use class-based services for orchestration-heavy flows (agents, simulation lifecycle, usage accounting).

src/core/agents/dynamic_service.py -> DynamicAgentService
src/core/analytics/admin_analytics_service.py -> AdminAnalyticsService (API router now thin delegator)
src/core/simulation/lifecycle_service.py -> SimulationLifecycleService
src/core/simulation/scenario_seeding_service.py -> ScenarioSeedingService
src/core/ai_usage/recording_service.py -> AIUsageRecordingService
src/core/tasks/workflow_service.py -> TaskWorkflowService
src/core/messages/orchestration_service.py -> MessageOrchestrationService
src/core/admin/diagnostics_service.py -> AdminDiagnosticsService
src/apis/simulation_admin/services/task_admin_service.py -> task admin CRUD/service boundary (router delegates transport/auth only)

src/apis/* may depend on src/core/*, src/memory/*, src/common/*, src/configs/*.
src/core/* may depend on repositories and shared/common code, but should not import API routers.
src/memory/* should stay storage-focused and not import API layers.
Cross-domain coordination should happen through service interfaces, not ad-hoc utility imports.

Legacy agent shims are retired:
- removed src/core/agents/agent_router.py
- removed src/core/agents/agent_response.py
- canonical response generator path: src/core/agents/tone_response_generator.py
Contract enforcement: tests/contract/test_backend_legacy_agent_imports.py blocks reintroduction of removed import paths and removed files.
Prefer one canonical implementation path for each major service.