Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+178
@@ -0,0 +1,178 @@
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user