chore: merge main

Author: a-klos

docs/UI_Customization.md

@@ -12,55 +12,68 @@ The RAG Template frontend supports several customization options:
 - **Logos** for light and dark mode
 - **Brand colors and themes** (Tailwind v4 + daisyUI v5)
 
+## Quick Start (Most Common Rebranding)
+
+If you just want to rename/rebrand the UI, these are the usual knobs:
+
+1. **Bot display name**: set `VITE_BOT_NAME`
+2. **Welcome message text**: edit `services/frontend/libs/i18n/chat/en.json` → `chat.initialMessage` (keep `{bot_name}`)
+3. **Navigation logo**: set `VITE_UI_LOGO_PATH_LIGHT` / `VITE_UI_LOGO_PATH_DARK` and add the files under each app’s `public/assets/`
+4. **Brand colors**: edit `services/frontend/libs/ui-styles/src/tailwind.css` (daisyUI theme tokens)
+5. **App titles + favicons**: edit `services/frontend/apps/*/index.html` and `services/frontend/apps/*/public/favicon.ico`
+
+## How Configuration Works (Build-Time vs Runtime)
+
+Vite apps are **static builds**. By default, all `VITE_*` variables are read at **build time** and baked into the built JS/CSS.
+
+This repository also supports **runtime overrides** in container deployments:
+
+- `services/frontend/.env.production` contains placeholder values like `VITE_BOT_NAME=VITE_BOT_NAME`
+- `services/frontend/env.sh` replaces those placeholder strings inside built `*.js`/`*.css` files at startup
+
+That replacement only happens if you **run `env.sh` against the directory that nginx serves** (default: `/usr/share/nginx/html`).
+
+| Scenario | Where to set `VITE_BOT_NAME` | When it takes effect |
+|---|---|---|
+| Local dev (`npm run chat:serve`) | `services/frontend/.env.development` (or `.env.development.local`) | on server restart |
+| Static hosting (S3, nginx without `env.sh`) | build environment or `services/frontend/.env.production` with real values | at build time |
+| Docker/Kubernetes (with `env.sh`) | container env vars + `env.sh` run at startup (in `infrastructure/rag/values.yaml` set `frontend.envs.vite.VITE_BOT_NAME`) | at container startup |
+
 ## Configuration Options
 
 ### Environment Variables
 
-All customization is done through environment variables that can be set at build time or runtime:
+UI rebranding uses `VITE_*` environment variables (see “Build-Time vs Runtime” above):
 
 | Variable | Description | Default Value | Example |
 |----------|-------------|---------------|---------|
 | `VITE_BOT_NAME` | The AI assistant's display name | "Knowledge Agent" | "DocBot" |
 | `VITE_UI_LOGO_PATH` | Common path to the main navigation logo (fallback for both light/dark) | "/assets/navigation-logo.svg" | "/assets/my-logo.png" |
 | `VITE_UI_LOGO_PATH_LIGHT` | Path to logo used in light mode (falls back to `VITE_UI_LOGO_PATH`) | — | "/assets/logo-light.svg" |
 | `VITE_UI_LOGO_PATH_DARK` | Path to logo used in dark mode (falls back to `VITE_UI_LOGO_PATH`) | — | "/assets/logo-dark.svg" |
-| `VITE_UI_THEME_DEFAULT` | Default theme when user first visits | "light" | "dark" |
-| `VITE_UI_THEME_OPTIONS` | Available theme options (comma-separated) | "light,dark" | "light,dark,auto" |
-
-### Bot Name Customization
-
-The bot name appears in the initial welcome message in the chat interface.
-
-**Default Message:**
+| `VITE_UI_THEME_DEFAULT` | Default theme when user first visits | "dark" | "light" |
+| `VITE_UI_THEME_OPTIONS` | Available theme options (comma-separated) | "light,dark" | "light" |
 
-```text
-Hi 👋, I'm your AI Assistant Knowledge Agent, here to support you with any questions regarding the provided documents!
-```
+### Bot Name & Welcome Message
 
-**Setting Custom Bot Name:**
+The bot name is read from `VITE_BOT_NAME` (see `services/frontend/libs/shared/settings.ts`) and is used in:
 
-1. **Development Environment:**
+- the sender name for assistant chat bubbles (`services/frontend/libs/chat-app/ui/ChatMessages.vue`)
+- the first “welcome” message when a chat session starts (`services/frontend/libs/chat-app/data-access/+state/chat.store.ts`)
 
-   ```bash
-   # In your .env file
-   VITE_BOT_NAME=DocBot
-   ```
+#### Change the bot name
 
-2. **Docker/Production:**
+- **Local development**: set `VITE_BOT_NAME` in `services/frontend/.env.development` (or create `services/frontend/.env.development.local`) and restart `npm run chat:serve`.
+- **Build-time (no runtime injection)**: set `VITE_BOT_NAME` in your environment before building (for example `VITE_BOT_NAME="Acme Assistant" npm -C services/frontend run chat:build`).
+- **Runtime (Docker/Kubernetes)**: set `VITE_BOT_NAME` in the container environment and ensure `services/frontend/env.sh` runs (see “Docker Deployment” / “Kubernetes/Helm Deployment” below).
 
-   ```bash
-   # Environment variable
-   export VITE_BOT_NAME="Your Custom Bot Name"
-   ```
+#### Change the welcome message text
 
-3. **Kubernetes/Helm:**
+Edit the translation string and keep `{bot_name}` for interpolation:
 
-   ```yaml
-   # In your values.yaml or deployment
-   env:
-     - name: VITE_BOT_NAME
-       value: "Corporate Knowledge Assistant"
-   ```
+Files:
+- `services/frontend/libs/i18n/chat/en.json`
+- `services/frontend/libs/i18n/chat/de.json`
 
 ### Logo Customization
 
@@ -93,8 +106,8 @@ The logo appears in the navigation header of both chat and admin applications. Y
 
 **Fallback order:**
 
-- Light: `VITE_UI_LOGO_PATH_LIGHT` → `VITE_UI_LOGO_PATH` → `/assets/navigation-logo.svg` (default asset exists in both apps: [chat](../services/frontend/apps/chat-app/public/assets/navigation-logo.svg), [admin](../services/frontend/apps/admin-app/public/assets/navigation-logo.svg))
-- Dark: `VITE_UI_LOGO_PATH_DARK` → `VITE_UI_LOGO_PATH` → `/assets/navigation-logo.svg` (default asset exists in both apps: [chat](../services/frontend/apps/chat-app/public/assets/navigation-logo.svg), [admin](../services/frontend/apps/admin-app/public/assets/navigation-logo.svg))
+- Light: `VITE_UI_LOGO_PATH_LIGHT` → `VITE_UI_LOGO_PATH` → `/assets/navigation-logo-light.svg` (default asset exists in both apps: [chat](../services/frontend/apps/chat-app/public/assets/navigation-logo-light.svg), [admin](../services/frontend/apps/admin-app/public/assets/navigation-logo-light.svg))
+- Dark: `VITE_UI_LOGO_PATH_DARK` → `VITE_UI_LOGO_PATH` → `/assets/navigation-logo-dark.svg` (default asset exists in both apps: [chat](../services/frontend/apps/chat-app/public/assets/navigation-logo-dark.svg), [admin](../services/frontend/apps/admin-app/public/assets/navigation-logo-dark.svg))
 
 **Examples:**
 
@@ -107,13 +120,37 @@ VITE_UI_LOGO_PATH_DARK=/assets/company-logo-dark.svg
 VITE_UI_LOGO_PATH=/assets/company-logo.svg
 ```
 
+### Other Rebranding Assets
+
+#### Chat avatars (user + assistant)
+
+The chat bubbles use static avatar files by default:
+
+- `services/frontend/apps/chat-app/public/assets/ai-avatar.svg`
+- `services/frontend/apps/chat-app/public/assets/user.svg`
+
+Replace those files (keep the same filenames), or update the constants in `services/frontend/libs/chat-app/ui/ChatMessages.vue`.
+
+#### Favicons
+
+- `services/frontend/apps/chat-app/public/favicon.ico`
+- `services/frontend/apps/admin-app/public/favicon.ico`
+
+#### Browser tab titles
+
+- `services/frontend/apps/chat-app/index.html` (`<title>`)
+- `services/frontend/apps/admin-app/index.html` (`<title>`)
+
 ### Theme System (Tailwind v4 + daisyUI v5)
 
 The frontend uses Tailwind v4 with daisyUI v5. In the following, we describe how to customize the theme using central CSS (recommended for brand colors shared by both apps):
 
 - File: `services/frontend/libs/ui-styles/src/tailwind.css`
 - This file loads Tailwind v4 and defines daisyUI themes via CSS `@plugin` blocks.
-- Update semantic tokens under the `@plugin "daisyui/theme"` blocks:
+- Themes are defined in two blocks:
+  - `light`: Light mode
+  - `dark`: Dark mode (default via `VITE_UI_THEME_DEFAULT`)
+- Update semantic tokens under the `@plugin "daisyui/theme"` blocks, for example:
 
 ```css
 --color-primary: #a90303;            /* CTA/buttons */
@@ -122,17 +159,63 @@ The frontend uses Tailwind v4 with daisyUI v5. In the following, we describe how
 --color-base-200: #EDEDED;           /* cards */
 ```
 
+Common class ↔ token mapping:
+
+- `btn btn-primary`, `bg-primary`, `text-primary` → `--color-primary` / `--color-primary-content`
+- `bg-secondary`, `text-secondary-content` → `--color-secondary` / `--color-secondary-content`
+- `bg-base-100/200/300`, `border-base-300`, `text-base-content` → `--color-base-*` / `--color-base-content`
+
+Custom CSS variables used by this repo are also defined per theme in `tailwind.css`:
+
+- `--scrollbar-track` / `--scrollbar-thumb` (scrollbar styling)
+- `--base-200-highlight` (highlight “jump to source” anchors)
+
 Theme behavior:
 
-- Default theme and options are set by env vars: `VITE_UI_THEME_DEFAULT`, `VITE_UI_THEME_OPTIONS`
-- The selected theme is stored in `localStorage` under `app-theme`
-- Theme switching updates `html[data-theme]` so daisyUI variables apply
+1. **Set Default Theme:**
+
+   ```bash
+   # Users will see dark mode by default
+   VITE_UI_THEME_DEFAULT=dark
+   ```
+
+1. **Configure Available Options:**
+
+   ```bash
+   # Only allow light mode (remove theme toggle)
+   VITE_UI_THEME_OPTIONS=light
+
+   # Support both themes (default)
+   VITE_UI_THEME_OPTIONS=light,dark
+   ```
+
+**Theme Behavior:**
+
+- Theme preference is saved in browser's localStorage
+- Theme persists across browser sessions
+- The built-in theme toggle is shown only when both `light` and `dark` are available
+- Manual theme switching overrides the default setting
+- Theme selection is stored under `localStorage["app-theme"]` and applied via `html[data-theme]`
+
+### Markdown / Chat Content Styling
+
+Chat answers, user prompts, and citations are rendered from Markdown via `marked` (see `services/frontend/libs/shared/utils/src/lib/marked.utils.ts`) and styled via global CSS in `services/frontend/libs/shared/global.css`.
+
+Rebrandable bits:
+
+- Code blocks: `--chat-code-*` variables and `.chat-code-block*` styles
+- Typography: `.prose` overrides keep headings/links readable across themes
 
 ## Development Setup
 
 ### Local Development
 
-1. **Create/modify `.env` file in frontend directory** (services/frontend/.env):
+Vite reads env files from `services/frontend/`. Common ones:
+
+- `services/frontend/.env.development` / `services/frontend/.env.development.local` (local dev)
+- `services/frontend/.env.production` / `services/frontend/.env.production.local` (production build)
+
+1. **Create/modify an env file** (recommended: `services/frontend/.env.development.local`):
 
    ```bash
    # Bot customization
@@ -159,31 +242,42 @@ Theme behavior:
 
 ### Docker Deployment
 
-For Docker deployments, the frontend uses a special script (services/frontend/env.sh) to replace environment variables at runtime:
+The app Docker images are built from:
 
-1. **Set environment variables in your container:**
+- `services/frontend/apps/chat-app/Dockerfile`
+- `services/frontend/apps/admin-app/Dockerfile`
 
-   ```dockerfile
-   ENV VITE_BOT_NAME="Production Assistant"
-   ENV VITE_UI_LOGO_PATH_LIGHT="/assets/prod-logo-light.svg"
-   ENV VITE_UI_LOGO_PATH_DARK="/assets/prod-logo-dark.svg"
-   ENV VITE_UI_THEME_DEFAULT="light"
-   ```
+These images contain:
+
+- built files under `/app/frontend` (read-only)
+- `env.sh` at `/app/env.sh`
+- nginx serving `/usr/share/nginx/html`
+
+To use runtime variables in Docker, you must ensure the container runs:
 
-1. **The env.sh script automatically replaces variables** in built JS/CSS files when the container starts. See [services/frontend/env.sh](../services/frontend/env.sh).
+```sh
+cp -r /app/frontend/. /usr/share/nginx/html && /bin/sh /app/env.sh
+```
+
+before nginx serves the files (otherwise placeholders like `VITE_BOT_NAME` will remain).
+
+See `services/frontend/env.sh` for details, including `TARGET_DIR` override.
 
 ### Kubernetes/Helm Deployment
 
-1. **Configure in your Helm values.yaml** (example chart values at [infrastructure/rag/values.yaml](../infrastructure/rag/values.yaml)):
+The Helm chart wires env vars via `frontend.envs.vite` into a ConfigMap and mounts a writable `/usr/share/nginx/html`. It also runs the copy + `env.sh` step (see `infrastructure/rag/templates/frontend/deployment.yaml`).
+
+1. **Configure in your Helm `values.yaml`** (example values at [infrastructure/rag/values.yaml](../infrastructure/rag/values.yaml)):
 
    ```yaml
    frontend:
-     env:
-       VITE_BOT_NAME: "Enterprise Knowledge Bot"
-       VITE_UI_LOGO_PATH_LIGHT: "/assets/enterprise-logo-light.svg"
-       VITE_UI_LOGO_PATH_DARK: "/assets/enterprise-logo-dark.svg"
-       VITE_UI_THEME_DEFAULT: "dark"
-       VITE_UI_THEME_OPTIONS: "light,dark"
+     envs:
+       vite:
+         VITE_BOT_NAME: "Enterprise Knowledge Bot"
+         VITE_UI_LOGO_PATH_LIGHT: "/assets/enterprise-logo-light.svg"
+         VITE_UI_LOGO_PATH_DARK: "/assets/enterprise-logo-dark.svg"
+         VITE_UI_THEME_DEFAULT: "dark"
+         VITE_UI_THEME_OPTIONS: "light,dark"
    ```
 
 2. **Or use ConfigMap:**
@@ -203,23 +297,12 @@ For Docker deployments, the frontend uses a special script (services/frontend/en
 
 ### Adding Custom Themes
 
-To add themes beyond light/dark, update both the settings and the theme source:
+This repo is optimized for `light`/`dark` theming. You can still add a custom theme, but note:
 
-1. **Update the settings configuration** in [services/frontend/libs/shared/settings.ts](../services/frontend/libs/shared/settings.ts):
+- The built-in UI toggle only switches between `light` and `dark` (`services/frontend/libs/shared/ui/ThemeToggle.vue`).
+- If you want a custom theme without adding a theme picker, set `VITE_UI_THEME_OPTIONS` to a single theme and the toggle will disappear.
 
-   ```typescript
-   // frontend/libs/shared/settings.ts
-   const defaultSettings: AppSettings = {
-     ui: {
-       theme: {
-         default: "light",
-         options: ["light", "dark", "brand-red"], // Add your theme
-       },
-     },
-   };
-   ```
-
-2. Define the theme either e.g. in CSS (recommended for shared branding):
+To add a custom theme, define it in `services/frontend/libs/ui-styles/src/tailwind.css`:
 
 CSS (Tailwind v4):
 
@@ -232,6 +315,13 @@ CSS (Tailwind v4):
 }
 ```
 
+Then select it via env vars:
+
+```bash
+VITE_UI_THEME_DEFAULT=brand-red
+VITE_UI_THEME_OPTIONS=brand-red
+```
+
 ### Internationalization
 
 Bot names and messages support internationalization:
@@ -263,9 +353,12 @@ Bot names and messages support internationalization:
 
 ### Bot Name Not Updating
 
-- **Issue**: Bot name shows as `{bot_name}` instead of actual name
-- **Cause**: Vue computed property not accessed correctly
-- **Solution**: Use `initialMessage.value` instead of `initialMessage` in the store
+- **Issue**: Bot name stays at the default or shows a placeholder value (e.g. `VITE_BOT_NAME`)
+- **Cause**: Runtime env replacement did not run (Vite env vars are build-time by default)
+- **Solutions**:
+  - Ensure `services/frontend/.env.production` contains placeholders for the variables you want to replace (this repo includes `VITE_BOT_NAME`, `VITE_UI_*`, etc.)
+  - Ensure the container runs `env.sh` after copying the built files into `/usr/share/nginx/html`
+  - Verify the variable is set in the container environment (Kubernetes `ConfigMap`/`Secret`, Docker `-e`, etc.)
 
 ### Logo Not Loading / Wrong for Theme
 
@@ -291,6 +384,7 @@ Bot names and messages support internationalization:
 - **Issue**: Customization works in development but not production
 - **Cause**: Vite environment variables are build-time only
 - **Solutions**:
+  - Ensure the variables exist as placeholders at build time (see `services/frontend/.env.production`)
   - For Docker: Ensure `env.sh` script runs after copying files
   - For Kubernetes: Use ConfigMap/Secret with proper mounting
   - Verify environment variables are set in container

infrastructure/README.md

@@ -257,6 +257,8 @@ frontend:
 
 The following values should be adjusted for the deployment:
 
+> ⓘ INFO: If the backend pod gets `OOMKilled` (exit code `137`) on local k3d/Tilt setups, reduce `backend.workers` (each uvicorn worker is a separate Python process), disable reranking `RERANKER_ENABLED: false` or pin a smaller Flashrank model (e.g. `RERANKER_MODEL: ms-marco-TinyBERT-L-2-v2`), and/or increase the memory available to Docker/k3d.
+
 ```yaml
 backend:
   secrets:

infrastructure/rag/templates/_admin_backend_and_extractor_helpers.tpl

@@ -68,6 +68,10 @@
 {{- printf "%s-source-uploader-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{- define "configmap.extractorSitemapName" -}}
+{{- printf "%s-extractor-sitemap-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
 # image
 {{- define "adminBackend.fullImageName" -}}
 {{- $tag := default .Chart.AppVersion .Values.adminBackend.image.tag -}}

infrastructure/rag/templates/extractor/configmap.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ template "configmap.extractorSitemapName" . }}
+data:
+  {{- range $key, $value := .Values.extractor.envs.sitemap }}
+  {{ $key }}: {{ $value | quote }}
+  {{- end }}

infrastructure/rag/templates/extractor/deployment.yaml

@@ -110,6 +110,8 @@ spec:
         envFrom:
           - configMapRef:
               name: {{ template "configmap.s3Name" . }}
+          - configMapRef:
+              name: {{ template "configmap.extractorSitemapName" . }}
           - secretRef:
               name: {{ template "secret.s3Name" . }}
         {{- $hfCacheDir := include "extractor.huggingfaceCacheDir" . }}