DOC-3498: tinymceai on-premises documentation

-scripts/render-mermaid.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# Re-renders all .mmd Mermaid sources to .svg in the on-premises images folder.
+#
+# Usage (from repo root):
+#   ./-scripts/render-mermaid.sh
+#
+# Requirements:
+#   Node.js (npx downloads @mermaid-js/mermaid-cli automatically)
+#
+set -euo pipefail
+
+DIAGRAM_DIR="modules/ROOT/images/tinymceai-on-premises"
+CONFIG_FILE=$(mktemp)
+
+cat > "$CONFIG_FILE" << 'JSON'
+{
+  "htmlLabels": false,
+  "flowchart": { "htmlLabels": false, "useMaxWidth": true },
+  "sequence": { "useMaxWidth": true },
+  "theme": "default"
+}
+JSON
+
+trap 'rm -f "$CONFIG_FILE"' EXIT
+
+count=0
+for mmd in "$DIAGRAM_DIR"/*.mmd; do
+  [ -f "$mmd" ] || continue
+  svg="${mmd%.mmd}.svg"
+  name=$(basename "$mmd")
+  printf "  Rendering %s\n" "$name"
+  npx -y @mermaid-js/mermaid-cli -i "$mmd" -o "$svg" \
+    -c "$CONFIG_FILE" --backgroundColor white 2>/dev/null
+
+  # Mermaid outputs width="100%" which has no intrinsic size in <img> tags.
+  # Replace with the actual pixel width from the viewBox so browsers can
+  # calculate the correct aspect ratio when the page scales the image.
+  vb_width=$(grep -o 'viewBox="[^"]*"' "$svg" | head -1 | awk -F'[ "]' '{print $4}')
+  if [ -n "$vb_width" ]; then
+    vb_int=$(printf "%.0f" "$vb_width")
+    perl -i -pe "s/width=\"100%\"/width=\"${vb_int}\"/" "$svg"
+  fi
+
+  count=$((count + 1))
+done
+
+printf "\nRendered %d diagrams in %s\n" "$count" "$DIAGRAM_DIR"

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-2.mmd

@@ -0,0 +1,14 @@
+flowchart LR
+    subgraph Tenants[Your SaaS customers]
+        CA[Customer A users]
+        CB[Customer B users]
+        CC[Customer C users]
+    end
+    subgraph AISvc[Single AI service deployment]
+        EA[Environment A<br>access keys A<br>isolated conversations]
+        EB[Environment B<br>access keys B<br>isolated conversations]
+        EC[Environment C<br>access keys C<br>isolated conversations]
+    end
+    CA --> EA --> OpenAI[OpenAI]
+    CB --> EB --> Anthropic[Anthropic]
+    CC --> EC --> Azure[Azure OpenAI]

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-3.mmd

@@ -0,0 +1,8 @@
+flowchart LR
+    Lawyer[TinyMCE editor<br>used by lawyer] <--> AI[AI Service]
+    AI -->|tools/call| MCP1[MCP: contract-db]
+    AI -->|tools/call| MCP2[MCP: compliance-checker]
+    AI -->|tools/call| MCP3[MCP: precedent-search]
+    MCP1 --> ContractDB[(Contract clause<br>repository)]
+    MCP2 --> ComplianceRules[(Regulatory<br>rule sets)]
+    MCP3 --> PrecedentIdx[(Precedent<br>search index)]

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-1.mmd

@@ -0,0 +1,26 @@
+flowchart TB
+    Browser["Browser<br>TinyMCE editor + tinymceai plugin"]
+    TokenEP["Your token endpoint<br>signs HS256 JWTs"]
+    Browser -->|"HTTPS"| TokenEP
+    Browser -->|"HTTPS + Bearer JWT"| LB
+
+    subgraph App["Application layer (stateless, +N replicas)"]
+        LB["Reverse proxy / Load balancer<br>nginx · ALB · K8s Ingress<br>TLS termination · SSE pass-through"]
+        AI1["ai-service"]
+        LB -->|"HTTP"| AI1
+    end
+
+    subgraph Data["Shared data layer"]
+        DB[("SQL database<br>MySQL 8.0+ / PostgreSQL 13+")]
+        Cache[("Redis 3.2.6+")]
+        Storage[("File storage<br>S3 · Azure Blob · filesystem")]
+    end
+
+    AI1 <-->|"read/write"| DB
+    AI1 <-->|"read/write"| Cache
+    AI1 <-->|"read/write"| Storage
+
+    AI1 -->|"HTTPS"| LLM["LLM provider<br>OpenAI · Anthropic · Google ·<br>Azure · Bedrock · Vertex ·<br>self-hosted"]
+
+    AI1 -.->|"telemetry"| Obs["OpenTelemetry · Langfuse"]
+    AI1 -.->|"tool calls"| MCP["MCP servers"]

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-2.mmd

@@ -0,0 +1,15 @@
+flowchart TD
+    Start([New deployment]) --> Q1{Evaluating or<br>going to production?}
+    Q1 -->|Evaluating locally| Compose[Docker Compose<br>all services on one host<br>Getting started guide]
+    Q1 -->|Production| Q2{Container orchestrator?}
+    Q2 -->|Kubernetes| K8s[Kubernetes deployment<br>Production guide]
+    Q2 -->|AWS ECS / Fargate| ECS[ECS task definition<br>Production guide]
+    Q2 -->|Docker / Podman on VMs| VMs[Docker or Podman compose<br>Database guide]
+    Compose --> DB{Database?}
+    K8s --> DB
+    ECS --> DB
+    VMs --> DB
+    DB -->|Managed cloud DB| Managed[RDS · Cloud SQL ·<br>Azure Database]
+    DB -->|Self-managed| Self[Containers or native install]
+    Managed --> Done([Continue with<br>LLM providers guide])
+    Self --> Done

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-3.mmd

@@ -0,0 +1,18 @@
+flowchart TB
+    Internet([Internet]) --> Ingress[Ingress controller<br>nginx-ingress · ALB controller<br>proxy-buffering off]
+    Ingress --> SvcAI[Service: ai-service]
+    SvcAI --> Pod1[Pod: ai-service replica 1]
+    SvcAI --> Pod2[Pod: ai-service replica 2]
+    SvcAI --> PodN[Pod: ai-service replica N]
+    Pod1 --> SvcDB[Service: database<br>or external RDS]
+    Pod2 --> SvcDB
+    PodN --> SvcDB
+    Pod1 --> SvcRedis[Service: redis<br>or external ElastiCache]
+    Pod2 --> SvcRedis
+    PodN --> SvcRedis
+    Pod1 --> S3[(S3 / Azure Blob)]
+    Pod2 --> S3
+    PodN --> S3
+    HPA[HorizontalPodAutoscaler] -. scales .-> Pod1
+    HPA -. scales .-> Pod2
+    HPA -. scales .-> PodN

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-4.mmd

@@ -0,0 +1,25 @@
+flowchart LR
+    subgraph PR[PROVIDERS env var]
+        P1["my-openai-key<br>type: openai<br>apiKeys: [sk-...]"]
+        P2["my-bedrock<br>type: bedrock<br>credentials: {...}"]
+        P3["my-ollama<br>type: openai-compatible<br>baseUrl: .../v1"]
+    end
+    subgraph MD[MODELS env var]
+        M1["id: gpt-4.1<br>provider: my-openai-key<br>features: [...]"]
+        M2["id: us.anthropic.claude-sonnet-4-...<br>provider: my-bedrock<br>features: [...]"]
+        M3["id: qwen3:0.6b<br>provider: my-ollama<br>features: [...]"]
+    end
+    subgraph JWT[JWT auth.ai.permissions]
+        K1["ai:models:my-openai-key:gpt-4.1"]
+        K2["ai:models:my-bedrock:us.anthropic.claude-sonnet-4-..."]
+        K3["ai:models:my-ollama:qwen3:0.6b"]
+    end
+    M1 -.provider key.-> P1
+    M2 -.provider key.-> P2
+    M3 -.provider key.-> P3
+    K1 -.gates access.-> M1
+    K2 -.gates access.-> M2
+    K3 -.gates access.-> M3
+    M1 ==>|forwarded| LLM1[OpenAI API]
+    M2 ==>|forwarded| LLM2[AWS Bedrock]
+    M3 ==>|forwarded| LLM3[Local Ollama]

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-5.mmd

@@ -0,0 +1,29 @@
+sequenceDiagram
+    autonumber
+    actor User
+    participant Editor as TinyMCE editor<br>tinymceai plugin
+    participant App as Your backend<br>token endpoint
+    participant AI as AI service
+    participant LLM as LLM provider
+
+    User->>Editor: Triggers an AI feature
+    Editor->>App: POST /api/ai-token<br>session cookie or Bearer
+    App->>App: Authenticate the user
+    Note over App: Sign HS256 JWT with API Secret<br>aud = environment ID<br>sub = user ID<br>auth.ai.permissions = [...]
+    App-->>Editor: { token: eyJ... }
+    Editor->>AI: POST /v1/conversations/id/messages<br>Authorization: Bearer eyJ...
+    AI->>AI: Verify HS256 signature<br>check aud, exp, permissions
+
+    alt Token valid and permissions allow
+        AI->>LLM: Forward prompt
+        LLM-->>AI: Stream response chunks
+        AI-->>Editor: SSE text-delta events
+    else Signature does not match
+        AI-->>Editor: 401 invalid-jwt-signature
+    else aud not registered with AI runtime
+        AI-->>Editor: 401 invalid-jwt-payload
+    else Past expiry plus 60s leeway
+        AI-->>Editor: 401 invalid-jwt
+    else Permissions do not cover action
+        AI-->>Editor: 200 with allowed false
+    end

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-6.mmd

@@ -0,0 +1,20 @@
+sequenceDiagram
+    autonumber
+    actor User
+    participant Editor as TinyMCE + tinymceai plugin
+    participant Provider as tinymceai_token_provider<br>your function
+    participant App as Your backend<br>token endpoint
+    participant AI as AI service
+
+    Note over Editor: tinymce.init runs once<br>plugin registers toolbar buttons
+    User->>Editor: Click AI button or open chat
+    Editor->>Provider: invoke
+    Provider->>App: fetch /api/ai-token<br>credentials include
+    App-->>Provider: { token eyJ... }
+    Provider-->>Editor: { token }
+    Editor->>AI: HTTPS request<br>Authorization Bearer eyJ...
+    AI-->>Editor: SSE stream
+    loop For each chunk
+        Editor->>Editor: Render streaming text
+    end
+    Note over Editor,Provider: Plugin re-invokes the provider<br>before token expiry<br>do not cache the JWT yourself

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-7.mmd

@@ -0,0 +1,4 @@
+flowchart LR
+    Editor[TinyMCE editor] <-->|"chat / quick actions"| AI[AI Service]
+    AI -->|"MCP tools/call"| MCP[MCP Server<br>knowledge-hub]
+    MCP -->|"read"| KB[(Confluence ·<br>Notion ·<br>GitBook ·<br>internal wiki)]

modules/ROOT/images/tinymceai-on-premises/database-setup-fig-1.mmd

@@ -0,0 +1,12 @@
+flowchart TD
+    Start([Where will MySQL/Postgres and Redis run?]) --> Q1{Evaluating or<br>deploying to prod?}
+    Q1 -->|Evaluating locally| Compose[Docker Compose<br>image: mysql:8.0 or postgres:16<br>+ redis:7]
+    Q1 -->|Deploying| Q2{Cloud or self-managed?}
+    Q2 -->|Cloud / managed services| Managed[AWS RDS · Cloud SQL ·<br>Azure Database<br>+ ElastiCache · Memorystore ·<br>Azure Cache for Redis]
+    Q2 -->|Self-managed| Q3{Container runtime<br>available?}
+    Q3 -->|Docker or Podman| Containers[Containers on the same<br>network or pod as ai-service]
+    Q3 -->|Native on host| Native[Native install<br>brew · apt · yum · dnf<br>AI service connects via<br>host.docker.internal]
+    Compose --> Verify([Verify: nc -zv host port<br>then start ai-service])
+    Managed --> Verify
+    Containers --> Verify
+    Native --> Verify

modules/ROOT/images/tinymceai-on-premises/framework-integration-fig-1.mmd

@@ -0,0 +1,20 @@
+sequenceDiagram
+    autonumber
+    actor User
+    participant Editor as TinyMCE + tinymceai plugin
+    participant Provider as tinymceai_token_provider<br>(your function)
+    participant App as Your backend<br>(token endpoint)
+    participant AI as AI service
+
+    Note over Editor: tinymce.init() runs once<br>plugin registers toolbar buttons
+    User->>Editor: Click AI button or open chat
+    Editor->>Provider: invoke()
+    Provider->>App: fetch('/api/ai-token', { credentials: 'include' })
+    App-->>Provider: { token: "eyJ..." }
+    Provider-->>Editor: { token }
+    Editor->>AI: HTTPS request<br>Authorization: Bearer eyJ...
+    AI-->>Editor: SSE stream
+    loop For each chunk
+        Editor->>Editor: Render streaming text
+    end
+    Note over Editor,Provider: Plugin re-invokes the provider<br>before token expiry — do not<br>cache the JWT yourself

modules/ROOT/images/tinymceai-on-premises/jwt-authentication-fig-1.mmd

@@ -0,0 +1,29 @@
+sequenceDiagram
+    autonumber
+    actor User
+    participant Editor as TinyMCE editor<br>(tinymceai plugin)
+    participant App as Your application backend<br>(token endpoint)
+    participant AI as AI service
+    participant LLM as LLM provider
+
+    User->>Editor: Triggers an AI feature
+    Editor->>App: tinymceai_token_provider callback<br>(e.g. POST /api/ai-token)
+    App->>App: Authenticate the user
+    Note over App: Sign HS256 JWT with API Secret<br>aud = environment ID<br>sub = user ID<br>auth.ai.permissions = [...]
+    App-->>Editor: { "token": "eyJ..." }
+    Editor->>AI: POST /v1/conversations/{id}/messages<br>Authorization: Bearer eyJ...
+    AI->>AI: Verify HS256 signature<br>check aud, exp, permissions
+
+    alt Token valid and permissions allow the action
+        AI->>LLM: Forward prompt
+        LLM-->>AI: Stream response chunks
+        AI-->>Editor: SSE: text-delta events
+    else Signature does not match
+        AI-->>Editor: 401 invalid-jwt-signature
+    else aud is not registered with AI runtime
+        AI-->>Editor: 401 invalid-jwt-payload
+    else Past expiry plus 60s leeway
+        AI-->>Editor: 401 invalid-jwt
+    else Permissions do not cover the action
+        AI-->>Editor: 200 with allowed:false
+    end

modules/ROOT/images/tinymceai-on-premises/mcp-web-integrations-architecture.mmd

@@ -0,0 +1,23 @@
+flowchart LR
+    Editor["TinyMCE editor"] <-->|"conversations (SSE)\nHTTP / HTTPS"| AI["AI Service\n(on-premises)"]
+
+    AI <-->|"inference\nHTTPS"| LLM["LLM Provider\nOpenAI · Anthropic · Google"]
+
+    AI <-->|"MCP tools/call\nHTTP"| MCP["MCP Server(s)\nStreamable HTTP"]
+    MCP <-->|"read"| KB["Confluence ·\nNotion · GitBook ·\ninternal wiki"]
+
+    AI <-->|"search query\nHTTP"| WS["Web Search\nWEBSEARCH_ENDPOINT"]
+    WS <-->|"HTTPS"| SearchAPI["Search API\nSerpAPI · Brave · etc."]
+
+    AI <-->|"scrape request\nHTTP"| WR["Web Scrape\nWEBRESOURCES_ENDPOINT"]
+    WR <-->|"HTTP/S"| Pages["Web pages"]
+
+    style AI fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
+    style Editor fill:#ECECFF,stroke:#9370DB
+    style MCP fill:#ECECFF,stroke:#9370DB
+    style WS fill:#ECECFF,stroke:#9370DB
+    style WR fill:#ECECFF,stroke:#9370DB
+    style LLM fill:#F1F8E9,stroke:#8BC34A
+    style KB fill:#F1F8E9,stroke:#8BC34A
+    style SearchAPI fill:#F1F8E9,stroke:#8BC34A
+    style Pages fill:#F1F8E9,stroke:#8BC34A

modules/ROOT/images/tinymceai-on-premises/overview-fig-1.mmd

@@ -0,0 +1,10 @@
+flowchart LR
+    Client["Client<br>application"]
+
+    Client -->|"1. fetch JWT"| Token["Token<br>endpoint"]
+    Client -->|"2. prompt + JWT"| AI["AI service<br>(container)"]
+    AI -->|"3. forward prompt"| LLM["LLM<br>provider"]
+    AI --- DB[("Database<br>+ Redis")]
+
+    LLM -.->|"4. stream response"| AI
+    AI -.->|"5. SSE stream"| Client

modules/ROOT/images/tinymceai-on-premises/overview-fig-2.mmd

@@ -0,0 +1,30 @@
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ECECFF', 'primaryBorderColor': '#9370DB', 'lineColor': '#333333', 'edgeLabelBackground': '#e8e8e8', 'fontSize': '16px' }, 'flowchart': { 'nodeSpacing': 40, 'rankSpacing': 80 }}}%%
+flowchart LR
+    subgraph Browser["Browser"]
+        App["TinyMCE editor\n(browser)"]
+    end
+
+    subgraph Service["Application layer"]
+        Token["Token endpoint\n(your server)"]
+        LB["Load balancer /\nreverse proxy\n(TLS termination)"]
+        AI["AI service\n(container)"]
+    end
+
+    subgraph Data["Data layer"]
+        DB[("SQL database\n(conversations, configs)")]
+        Redis[("Redis\n(cache, coordination)")]
+        Storage[("File storage\n(uploads, documents)")]
+    end
+
+    LLM["LLM provider"]
+
+    App -->|"1. request JWT"| Token
+    Token -->|"JWT"| App
+    App -->|"2. HTTPS"| LB
+    LB <-->|"HTTP / SSE"| AI
+    AI -->|"3. HTTPS"| LLM
+    LLM -->|"4. stream"| AI
+    LB -->|"5. SSE"| App
+    AI <-->|"read/write"| DB
+    AI <-->|"read/write"| Redis
+    AI <-->|"read/write"| Storage

modules/ROOT/images/tinymceai-on-premises/providers-guide-fig-1.mmd

@@ -0,0 +1,31 @@
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ECECFF', 'primaryBorderColor': '#9370DB', 'lineColor': '#333333', 'edgeLabelBackground': '#e8e8e8', 'fontSize': '14px' }, 'flowchart': { 'nodeSpacing': 30, 'rankSpacing': 60, 'wrappingWidth': 200 }}}%%
+flowchart LR
+    subgraph JWT["JWT auth.ai.permissions"]
+        K1["ai:models:my-openai-key:\ngpt-4.1"]
+        K2["ai:models:my-bedrock:\nclaude-sonnet-4"]
+        K3["ai:models:my-ollama:\nqwen3:0.6b"]
+    end
+
+    subgraph MD["MODELS env var · JSON array"]
+        M1["gpt-4.1\nprovider: my-openai-key"]
+        M2["claude-sonnet-4\nprovider: my-bedrock"]
+        M3["qwen3:0.6b\nprovider: my-ollama"]
+    end
+
+    subgraph PR["PROVIDERS env var · JSON object"]
+        P1["my-openai-key\ntype: openai"]
+        P2["my-bedrock\ntype: bedrock"]
+        P3["my-ollama\ntype: openai-compatible"]
+    end
+
+    K1 -->|"gates access"| M1
+    K2 -->|"gates access"| M2
+    K3 -->|"gates access"| M3
+
+    M1 -->|"provider key"| P1
+    M2 -->|"provider key"| P2
+    M3 -->|"provider key"| P3
+
+    P1 --> LLM1["OpenAI API"]
+    P2 --> LLM2["AWS Bedrock"]
+    P3 --> LLM3["Local Ollama"]