{
  "schemaVersion": "1.0",
  "id": "ai-chatbot-admin-managed",
  "title": "Admin-Managed AI Chatbot",
  "classification": "plugin-candidate",
  "status": "proposed",
  "owner": "feature-integration",
  "description": "Tenant-facing AI chatbot whose provider credentials, browser/runtime policy, and global availability are managed by admin/platform configuration.",
  "rationale": [
    "AI provider keys and browser automation capabilities are sensitive platform resources and should not be stored in tenant-owned settings by default.",
    "Tenant users can consume the chatbot while admin controls provider choice, budgets, allowed models, browser access, and safety policy.",
    "Browser-backed AI work is operationally different from normal request/response UI and should be declared as worker-backed before implementation."
  ],
  "codeAreas": [
    "apps/web/app/modules/chatbot",
    "apps/web/app/modules/ai",
    "apps/web/app/routes/admin/ai/*",
    "apps/web/app/routes/admin/chat/*",
    "apps/web/app/routes/app.$tenant/chat/*",
    "apps/web/app/components/ai-elements/*",
    "apps/web/app/utils/html-sanitizer.ts",
    "apps/api/src/app.ts",
    "/v1/ai/upload",
    "apps/worker",
    "packages/queue"
  ],
  "dependencies": [
    "core",
    "auth-tenancy",
    "admin-app-shell",
    "rows-entities-runtime"
  ],
  "consumers": [
    "plugin-candidates"
  ],
  "integration": {
    "ownership": "admin-managed",
    "surfaces": {
      "adminRoutes": [
        "apps/web/app/routes/admin/ai/*",
        "apps/web/app/routes/admin/chat/*",
        "admin settings for provider credentials, model policy, browser policy, and usage limits"
      ],
      "tenantRoutes": [
        "apps/web/app/routes/app.$tenant/chat/*",
        "tenant chatbot launcher or embedded assistant surface"
      ],
      "publicRoutes": [],
      "apiRoutes": [
        "/v1/ai/upload",
        "streaming chat endpoints",
        "worker enqueue/status endpoints if browser work is async"
      ]
    },
    "configuration": {
      "admin": [
        "AI provider API key approved for the deployment region",
        "Allowed model list",
        "Default model",
        "Browser automation enablement",
        "Browser allowlist/denylist policy",
        "Per-tenant feature enablement",
        "Global budget and rate limits"
      ],
      "tenant": [
        "Tenant-level enable/disable if admin allows it",
        "Tenant-facing chatbot context and display preferences",
        "Optional tenant knowledge/context selection without provider secrets"
      ],
      "environment": [
        "AI_PROCESSING_REGION",
        "MISTRAL_API_KEY",
        "MISTRAL_MODEL",
        "SCALEWAY_API_KEY",
        "SCALEWAY_MODEL",
        "SCALEWAY_BASE_URL",
        "SCALEWAY_REGION",
        "ALEPH_ALPHA_API_KEY",
        "ALEPH_ALPHA_MODEL",
        "ALEPH_ALPHA_BASE_URL",
        "AI_GENERATION_MAX_ESTIMATED_INPUT_COST_CENTS",
        "AI_GENERATION_RATE_LIMIT",
        "AI_GENERATION_RATE_LIMIT_WINDOW_MS",
        "BULLMQ_REDIS_URL",
        "BROWSER_RUNTIME_URL",
        "BROWSER_RUNTIME_API_KEY",
        "BROWSER_SESSION_TIMEOUT_MS"
      ],
      "secrets": [
        "AI provider API keys are admin/platform-owned.",
        "Provider keys must never be exposed in tenant routes, tenant JSON loaders, browser bundles, or client-visible config.",
        "Browser session credentials and proxy credentials are worker/platform-owned."
      ]
    },
    "workers": {
      "required": true,
      "queues": [
        "toolctrl.ai-chatbot",
        "toolctrl.browser-automation"
      ],
      "jobs": [
        "chat-completion",
        "browser-session-run",
        "browser-session-cleanup",
        "usage-flush"
      ],
      "notes": [
        "Short text-only chat can stream in request scope, but any browser-backed task must be queue/worker-backed.",
        "Worker jobs must receive scoped tenant/user/context IDs, not raw secrets from tenant input.",
        "Browser jobs must enforce admin-owned allowlist policy before navigation."
      ]
    },
    "externalProviders": [
      "deployment-region-ai-provider",
      "browser-runtime"
    ],
    "permissions": [
      "admin.ai.configure",
      "admin.ai.providers.update",
      "admin.ai.usage.view",
      "app.ai.chat.use"
    ],
    "auditEvents": [
      "admin.ai.provider_key.updated",
      "admin.ai.model_policy.updated",
      "admin.ai.browser_policy.updated",
      "tenant.ai_chatbot.enabled",
      "ai_chatbot.browser_job.started",
      "ai_chatbot.browser_job.completed",
      "ai_chatbot.browser_job.failed"
    ],
    "billingImpacts": [
      "AI token usage may need plan gates or usage metering.",
      "Browser runtime usage may need separate metering from text-token usage.",
      "Admin-owned provider keys mean platform billing exposure unless tenant pass-through billing is explicitly designed."
    ],
    "uat": [
      "Admin can save provider configuration without exposing the key to tenant responses or client bundles.",
      "Admin can enable/disable the chatbot for a tenant.",
      "Tenant can start a chat only when the feature is enabled and permission allows it.",
      "AI markdown and web-preview surfaces sanitize active HTML and restrict preview iframes to safe HTTP(S) targets.",
      "Browser-backed chat tasks run through a worker queue and enforce admin allowlist policy.",
      "Usage and key-policy changes emit audit events."
    ]
  },
  "boundaries": {
    "mustKeep": [
      "Provider secrets remain admin/platform-owned.",
      "Tenant surfaces only receive non-secret feature state and allowed options.",
      "Browser-backed tasks require worker isolation and navigation policy enforcement."
    ],
    "mayMoveToPlugin": [
      "All AI/chatbot/browser automation surfaces",
      "Provider-specific AI implementation",
      "Usage metering beyond core billing hooks"
    ],
    "mustNotTouch": [
      "Core auth/session logic except permission checks needed by this plugin.",
      "Core billing internals except explicit usage-meter hooks."
    ]
  },
  "pruning": {
    "phase": "planning",
    "action": "extract-plugin",
    "notes": [
      "Use this as the reference pattern for admin-managed tenant features that need provider secrets or workers.",
      "Do not implement browser automation in request scope."
    ]
  },
  "validation": {
    "source": [
      "docs/agent-playbooks/admin-managed-features.md",
      "docs/agent-playbooks/worker-backed-features.md",
      "docs/agent-playbooks/feature-integration.md"
    ],
    "lastReviewed": "2026-05-16"
  }
}