From a1b254a0b2669d3c84ed0a2a2de9fd2ac1fd8780 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:05:38 +0200
Subject: [PATCH 01/12] refactor: run sqlite migrations at startup

---
 docs/storage.md              |  5 +++--
 server/plugins/migrations.ts | 17 +++++++++++++++++
 server/utils/storage.ts      |  5 ++---
 3 files changed, 22 insertions(+), 5 deletions(-)
 create mode 100644 server/plugins/migrations.ts

diff --git a/docs/storage.md b/docs/storage.md
index 465ec65..f97a83a 100755
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -22,7 +22,8 @@ Configuration in `nuxt.config.ts`:
 
 ## Initialization
 
-- `initStorage()` in `server/utils/storage.ts` applies pending Drizzle migrations on first storage access.
+- `server/plugins/migrations.ts` applies pending Drizzle migrations when the Nitro server starts.
+- `initStorage()` in `server/utils/storage.ts` initializes the shared SQLite client after startup.
 - No bundled seed data is included in the repository.
 - Emoji cooldown state stays in server memory and is not part of persisted storage.
 
@@ -40,7 +41,7 @@ Reset all stored quiz data:
 rm -rf .data/
 ```
 
-The next runtime access recreates the SQLite database file.
+The next server start recreates the SQLite database file.
 
 ## Production Mounts
 
diff --git a/server/plugins/migrations.ts b/server/plugins/migrations.ts
new file mode 100644
index 0000000..50415b9
--- /dev/null
+++ b/server/plugins/migrations.ts
@@ -0,0 +1,17 @@
+import { defineNitroPlugin } from 'nitropack/runtime'
+import {
+  applyLocalMigrations,
+  getLocalDatabaseClient,
+} from '../database/local-sqlite'
+import { logger_error } from '../utils/logger'
+
+/** Applies pending SQLite migrations when the Nitro server starts. */
+export default defineNitroPlugin(() => {
+  try {
+    applyLocalMigrations(getLocalDatabaseClient().db)
+  }
+  catch (error: unknown) {
+    logger_error('SQLite migration startup error:', error)
+    throw error
+  }
+})
diff --git a/server/utils/storage.ts b/server/utils/storage.ts
index 8947ca2..c8ade27 100644
--- a/server/utils/storage.ts
+++ b/server/utils/storage.ts
@@ -20,7 +20,6 @@ import {
   deserializeQuestion,
 } from '../database/question-records'
 import {
-  applyLocalMigrations,
   getLocalDatabaseClient,
 } from '../database/local-sqlite'
 import {
@@ -45,12 +44,12 @@ function getQuestionById(questionId: string): Question | undefined {
   return row ? deserializeQuestion(row) : undefined
 }
 
-/** Initializes SQLite access and applies any pending migrations once. */
+/** Initializes SQLite access once after the startup migration plugin has run. */
 export async function initStorage(_event?: H3Event) {
   if (storageInitialized) return
 
   try {
-    applyLocalMigrations(getDatabase())
+    getDatabase()
     storageInitialized = true
   }
   catch (error: unknown) {

From 73c0e9b67e4df09490466986fe1e5e03b2db83f8 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:18:22 +0200
Subject: [PATCH 02/12] feat: add drizzle studio proxy

---
 nuxt.config.ts                                |   1 +
 .../drizzle-studio/app/[...asset].get.ts      |  45 ++++++++
 .../api/admin/drizzle-studio/app/index.get.ts |  35 ++++++
 server/routes/index.post.ts                   |  54 ++++++++++
 server/routes/init.ts                         |  10 ++
 server/utils/drizzle-studio.ts                | 100 ++++++++++++++++++
 6 files changed, 245 insertions(+)
 create mode 100644 server/api/admin/drizzle-studio/app/[...asset].get.ts
 create mode 100644 server/api/admin/drizzle-studio/app/index.get.ts
 create mode 100644 server/routes/index.post.ts
 create mode 100644 server/routes/init.ts
 create mode 100644 server/utils/drizzle-studio.ts

diff --git a/nuxt.config.ts b/nuxt.config.ts
index a37dd46..cca2b92 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -23,6 +23,7 @@ const configBase: InputConfig<NuxtConfig, ConfigLayerMeta> = {
     // Private keys (only available server-side)
     adminPassword: '123',
     adminUsername: 'admin',
+    drizzleStudioInternalPort: '64983',
     jwtSecret: 'tryUJ0zQbstPbTOrezme+Fv+KndzDNRx5lmSeelr2ial2/2yV8HqLeQ2felJafqf',
 
     // Public keys (available on both client and server)
diff --git a/server/api/admin/drizzle-studio/app/[...asset].get.ts b/server/api/admin/drizzle-studio/app/[...asset].get.ts
new file mode 100644
index 0000000..1482d04
--- /dev/null
+++ b/server/api/admin/drizzle-studio/app/[...asset].get.ts
@@ -0,0 +1,45 @@
+import { verifyAdmin } from '../../../../utils/auth'
+
+const DRIZZLE_STUDIO_APP_ORIGIN = 'https://local.drizzle.studio'
+const FORWARDED_HEADERS = [
+  'cache-control',
+  'content-type',
+  'etag',
+  'last-modified',
+]
+
+export default defineEventHandler(async (event) => {
+  await verifyAdmin(event)
+
+  const assetPath = event.context.params?.asset
+
+  if (!assetPath) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Drizzle Studio asset not found',
+    })
+  }
+
+  const requestUrl = getRequestURL(event)
+  const upstreamUrl = `${DRIZZLE_STUDIO_APP_ORIGIN}/${assetPath}${requestUrl.search}`
+  const response = await fetch(upstreamUrl)
+
+  if (!response.ok) {
+    throw createError({
+      statusCode: response.status,
+      statusMessage: `Failed to load Drizzle Studio asset: ${assetPath}`,
+    })
+  }
+
+  setResponseStatus(event, response.status, response.statusText)
+
+  for (const header of FORWARDED_HEADERS) {
+    const value = response.headers.get(header)
+
+    if (value) {
+      setHeader(event, header, value)
+    }
+  }
+
+  return new Uint8Array(await response.arrayBuffer())
+})
diff --git a/server/api/admin/drizzle-studio/app/index.get.ts b/server/api/admin/drizzle-studio/app/index.get.ts
new file mode 100644
index 0000000..c49ee1b
--- /dev/null
+++ b/server/api/admin/drizzle-studio/app/index.get.ts
@@ -0,0 +1,35 @@
+import { verifyAdmin } from '../../../../utils/auth'
+
+const DRIZZLE_STUDIO_APP_ORIGIN = 'https://local.drizzle.studio'
+
+/** Removes third-party analytics from the upstream Studio shell. */
+function sanitizeStudioHtml(html: string) {
+  const analyticsScript = new RegExp(
+    '<script defer="defer" data-site-id="local\\.drizzle\\.studio" '
+    + 'src="https:\\/\\/assets\\.onedollarstats\\.com\\/stonks\\.js"><\\/script>',
+  )
+
+  return html.replace(analyticsScript, '')
+}
+
+export default defineEventHandler(async (event) => {
+  await verifyAdmin(event)
+
+  const response = await fetch(`${DRIZZLE_STUDIO_APP_ORIGIN}/`)
+
+  if (!response.ok) {
+    throw createError({
+      statusCode: 502,
+      statusMessage: `Failed to load Drizzle Studio (${response.status})`,
+    })
+  }
+
+  setHeader(
+    event,
+    'content-type',
+    response.headers.get('content-type') || 'text/html; charset=utf-8',
+  )
+  setHeader(event, 'cache-control', 'no-store')
+
+  return sanitizeStudioHtml(await response.text())
+})
diff --git a/server/routes/index.post.ts b/server/routes/index.post.ts
new file mode 100644
index 0000000..9bdb774
--- /dev/null
+++ b/server/routes/index.post.ts
@@ -0,0 +1,54 @@
+import { verifyAdmin } from '../utils/auth'
+import {
+  ensureDrizzleStudioServer,
+  getDrizzleStudioInternalRpcUrl,
+} from '../utils/drizzle-studio'
+
+const FORWARDED_HEADERS = [
+  'cache-control',
+  'content-type',
+]
+
+export default defineEventHandler(async (event) => {
+  await verifyAdmin(event)
+  await ensureDrizzleStudioServer(event)
+
+  const rawBody = await readRawBody(event, false)
+  const requestBody = typeof rawBody === 'string'
+    ? rawBody
+    : rawBody
+      ? rawBody.toString('utf8')
+      : undefined
+
+  let response: Response
+
+  try {
+    response = await fetch(getDrizzleStudioInternalRpcUrl(event), {
+      method: 'POST',
+      headers: {
+        'accept': getHeader(event, 'accept') || 'application/json',
+        'content-type': getHeader(event, 'content-type') || 'application/json',
+      },
+      body: requestBody,
+    })
+  }
+  catch (error) {
+    throw createError({
+      statusCode: 502,
+      statusMessage: 'Failed to reach the Drizzle Studio proxy',
+      data: error instanceof Error ? { message: error.message } : undefined,
+    })
+  }
+
+  setResponseStatus(event, response.status, response.statusText)
+
+  for (const header of FORWARDED_HEADERS) {
+    const value = response.headers.get(header)
+
+    if (value) {
+      setHeader(event, header, value)
+    }
+  }
+
+  return await response.text()
+})
diff --git a/server/routes/init.ts b/server/routes/init.ts
new file mode 100644
index 0000000..a1e7eda
--- /dev/null
+++ b/server/routes/init.ts
@@ -0,0 +1,10 @@
+import { verifyAdmin } from '../utils/auth'
+
+export default defineEventHandler(async (event) => {
+  await verifyAdmin(event)
+
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Not Found',
+  })
+})
diff --git a/server/utils/drizzle-studio.ts b/server/utils/drizzle-studio.ts
new file mode 100644
index 0000000..899e089
--- /dev/null
+++ b/server/utils/drizzle-studio.ts
@@ -0,0 +1,100 @@
+import { startStudioSQLiteServer } from 'drizzle-kit/api'
+import type { H3Event } from 'h3'
+import * as schema from '../database/schema'
+import { getLocalDatabasePath } from '../database/local-config'
+
+const DRIZZLE_STUDIO_INTERNAL_HOST = '127.0.0.1'
+const DEFAULT_DRIZZLE_STUDIO_INTERNAL_PORT = 64983
+const DRIZZLE_STUDIO_STARTUP_TIMEOUT_MS = 15000
+const DRIZZLE_STUDIO_STARTUP_POLL_MS = 250
+
+declare global {
+  var __stageFlowDrizzleStudioStartup__: Promise<void> | undefined
+}
+
+/** Returns the internal port used by the embedded Drizzle Studio server. */
+function getDrizzleStudioInternalPort(event: H3Event) {
+  const config = useRuntimeConfig(event)
+  const port = Number(config.drizzleStudioInternalPort || DEFAULT_DRIZZLE_STUDIO_INTERNAL_PORT)
+
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: 'DRIZZLE_STUDIO_INTERNAL_PORT must be a valid TCP port',
+    })
+  }
+
+  return port
+}
+
+/** Returns the base URL of the internal Drizzle Studio server. */
+function getDrizzleStudioInternalUrl(event: H3Event) {
+  return `http://${DRIZZLE_STUDIO_INTERNAL_HOST}:${getDrizzleStudioInternalPort(event)}`
+}
+
+/** Polls the internal Studio server until it answers its init payload. */
+async function waitForDrizzleStudio(event: H3Event) {
+  const deadline = Date.now() + DRIZZLE_STUDIO_STARTUP_TIMEOUT_MS
+  const url = `${getDrizzleStudioInternalUrl(event)}/`
+  let lastError: unknown
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'accept': 'application/json',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ type: 'init' }),
+      })
+
+      if (response.ok) {
+        const payload = await response.json().catch(() => null)
+
+        if (payload && typeof payload === 'object' && 'dialect' in payload && payload.dialect === 'sqlite') {
+          return
+        }
+      }
+
+      lastError = new Error(`Unexpected Drizzle Studio response: ${response.status}`)
+    }
+    catch (error) {
+      lastError = error
+    }
+
+    await new Promise(resolve => setTimeout(resolve, DRIZZLE_STUDIO_STARTUP_POLL_MS))
+  }
+
+  throw createError({
+    statusCode: 502,
+    statusMessage: 'Drizzle Studio failed to start',
+    data: lastError instanceof Error ? { message: lastError.message } : undefined,
+  })
+}
+
+/** Starts Drizzle Studio once and waits until the local server is ready. */
+export async function ensureDrizzleStudioServer(event: H3Event) {
+  if (!globalThis.__stageFlowDrizzleStudioStartup__) {
+    globalThis.__stageFlowDrizzleStudioStartup__ = (async () => {
+      await startStudioSQLiteServer(schema, {
+        url: getLocalDatabasePath(),
+      }, {
+        host: DRIZZLE_STUDIO_INTERNAL_HOST,
+        port: getDrizzleStudioInternalPort(event),
+      })
+
+      await waitForDrizzleStudio(event)
+    })().catch((error) => {
+      globalThis.__stageFlowDrizzleStudioStartup__ = undefined
+      throw error
+    })
+  }
+
+  await globalThis.__stageFlowDrizzleStudioStartup__
+}
+
+/** Returns the root RPC endpoint exposed by the local Studio server. */
+export function getDrizzleStudioInternalRpcUrl(event: H3Event) {
+  return `${getDrizzleStudioInternalUrl(event)}/`
+}

From ade600e66868f05d24c7f5a91447b57ee8df5d81 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:18:30 +0200
Subject: [PATCH 03/12] feat: add admin database page

---
 app/pages/admin/database.vue | 94 ++++++++++++++++++++++++++++++++++++
 app/pages/admin/index.vue    |  7 +++
 2 files changed, 101 insertions(+)
 create mode 100644 app/pages/admin/database.vue

diff --git a/app/pages/admin/database.vue b/app/pages/admin/database.vue
new file mode 100644
index 0000000..5dcadb5
--- /dev/null
+++ b/app/pages/admin/database.vue
@@ -0,0 +1,94 @@
+<script setup lang="ts">
+definePageMeta({
+  layout: 'default',
+  middleware: 'auth',
+  footer: true,
+  background: true,
+  localeSwitcher: true,
+})
+
+const { t } = useI18n()
+const studioUrl = ref('')
+
+onMounted(() => {
+  const currentUrl = new URL(window.location.href)
+  const resolvedPort = currentUrl.port || (currentUrl.protocol === 'https:' ? '443' : '80')
+  const query = new URLSearchParams({
+    host: currentUrl.hostname,
+    port: resolvedPort,
+  })
+
+  studioUrl.value = `/api/admin/drizzle-studio/app/?${query.toString()}`
+})
+</script>
+
+<template>
+  <div class="mx-auto max-w-6xl p-5">
+    <UiPageTitle>{{ t('title') }}</UiPageTitle>
+
+    <p class="mb-5 text-center text-sm text-gray-600">
+      {{ t('description') }}
+    </p>
+
+    <div class="mb-5 flex flex-wrap justify-center gap-3">
+      <NuxtLink
+        class="block border-[3px] border-black bg-white px-4 py-3 text-sm uppercase transition-all duration-200
+          hover:translate-x-1 hover:shadow-[-5px_5px_0_#000]"
+        to="/admin"
+      >
+        {{ t('back') }}
+      </NuxtLink>
+
+      <a
+        v-if="studioUrl"
+        class="block border-[3px] border-black bg-black px-4 py-3 text-sm uppercase text-white
+          transition-all duration-200 hover:translate-x-1 hover:shadow-[-5px_5px_0_#000]"
+        :href="studioUrl"
+        rel="noopener noreferrer"
+        target="_blank"
+      >
+        {{ t('openNewTab') }}
+      </a>
+    </div>
+
+    <div class="overflow-hidden border-[3px] border-black bg-white">
+      <iframe
+        v-if="studioUrl"
+        class="h-[78vh] w-full bg-white"
+        :src="studioUrl"
+        :title="t('iframeTitle')"
+      />
+
+      <div
+        v-else
+        class="flex h-[78vh] items-center justify-center text-sm uppercase tracking-wide text-gray-500"
+      >
+        {{ t('loading') }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<i18n lang="yaml">
+en:
+  title: Database
+  description: Browse and edit the SQLite database through a server-side Drizzle Studio proxy.
+  back: Back to Admin
+  openNewTab: Open in New Tab
+  iframeTitle: Drizzle Studio
+  loading: Loading Studio
+de:
+  title: Datenbank
+  description: SQLite-Datenbank über einen serverseitigen Drizzle-Studio-Proxy durchsuchen und bearbeiten.
+  back: Zurück zur Admin
+  openNewTab: In neuem Tab öffnen
+  iframeTitle: Drizzle Studio
+  loading: Studio wird geladen
+ja:
+  title: データベース
+  description: サーバー側の Drizzle Studio プロキシ経由で SQLite データベースを参照、編集します。
+  back: 管理画面に戻る
+  openNewTab: 新しいタブで開く
+  iframeTitle: Drizzle Studio
+  loading: Studio を読み込み中
+</i18n>
diff --git a/app/pages/admin/index.vue b/app/pages/admin/index.vue
index f68fbbd..c0ef4fc 100644
--- a/app/pages/admin/index.vue
+++ b/app/pages/admin/index.vue
@@ -14,6 +14,7 @@ const subPages = computed(() => [
   { path: '/admin/results', label: t('results'), description: t('resultsDesc') },
   { path: '/admin/leaderboard', label: t('leaderboard'), description: t('leaderboardDesc') },
   { path: '/admin/emojis', label: t('emojis'), description: t('emojisDesc') },
+  { path: '/admin/database', label: t('database'), description: t('databaseDesc') },
 ])
 
 const logoutError = ref(false)
@@ -74,6 +75,8 @@ en:
   leaderboardDesc: Aggregated player scores across all published questions.
   emojis: Emoji Overlay
   emojisDesc: Floating emoji reactions overlay for presentations.
+  database: Database
+  databaseDesc: Open Drizzle Studio in a protected admin frame.
   logout: Logout
   logoutError: Logout failed. Please try again.
 de:
@@ -86,6 +89,8 @@ de:
   leaderboardDesc: Gesammelte Spielerpunktzahlen aller veröffentlichten Fragen.
   emojis: Emoji-Overlay
   emojisDesc: Schwebende Emoji-Reaktionen als Overlay für Präsentationen.
+  database: Datenbank
+  databaseDesc: Drizzle Studio in einem geschützten Admin-Frame öffnen.
   logout: Abmelden
   logoutError: Abmeldung fehlgeschlagen. Bitte versuchen Sie es erneut.
 ja:
@@ -98,6 +103,8 @@ ja:
   leaderboardDesc: 公開された全質問の累計プレイヤースコア。
   emojis: 絵文字オーバーレイ
   emojisDesc: プレゼンテーション用の浮遊する絵文字リアクションオーバーレイ。
+  database: データベース
+  databaseDesc: 保護された管理フレームで Drizzle Studio を開きます。
   logout: ログアウト
   logoutError: ログアウトに失敗しました。もう一度お試しください。
 </i18n>

From 222bab075351d874e7a34e68d31035ecaf7ba4d5 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:18:38 +0200
Subject: [PATCH 04/12] docs: note admin database route

---
 README.md           | 1 +
 docs/quick-start.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 06c67bd..6c71a70 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Perfect for:
 - **`/admin/results`** - Live results display
 - **`/admin/leaderboard`** - Player leaderboard
 - **`/admin/emojis`** - Floating emoji overlay
+- **`/admin/database`** - Embedded Drizzle Studio for database inspection
 
 ## Documentation
 
diff --git a/docs/quick-start.md b/docs/quick-start.md
index f74e9bf..193a030 100755
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -39,6 +39,7 @@ Get the quiz application running in minutes.
 - **Admin Dashboard**: http://localhost:3000/admin
 - **Live Results**: http://localhost:3000/admin/results
 - **Leaderboard**: http://localhost:3000/admin/leaderboard
+- **Database Admin**: http://localhost:3000/admin/database
 
 ## Default Credentials
 

From bf89023c8bb811e21a5c9267d93e791c52d666bc Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:18:43 +0200
Subject: [PATCH 05/12] docs: record drizzle studio proxy

---
 docs/api.md               | 14 ++++++++++++++
 docs/deployment-docker.md | 13 +++++++++++++
 docs/setup-production.md  |  2 ++
 3 files changed, 29 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index ea33ee4..d8da5c8 100755
--- a/docs/api.md
+++ b/docs/api.md
@@ -52,6 +52,20 @@ Verify authentication token (admin only).
 }
 ```
 
+## Database Admin
+
+### GET `/api/admin/drizzle-studio/app`
+
+Load the authenticated Drizzle Studio shell used by `/admin/database`.
+
+### GET `/api/admin/drizzle-studio/app/<asset>`
+
+Load Drizzle Studio static assets through the authenticated proxy.
+
+### POST `/`
+
+Internal admin-only Drizzle Studio RPC compatibility endpoint used by the embedded frame. Treat this as internal transport, not a public integration API.
+
 ## Questions
 
 ### GET `/api/questions`
diff --git a/docs/deployment-docker.md b/docs/deployment-docker.md
index f79edfc..7b53780 100644
--- a/docs/deployment-docker.md
+++ b/docs/deployment-docker.md
@@ -51,6 +51,15 @@ NUXT_ADMIN_PASSWORD=<your-strong-password>
 NUXT_JWT_SECRET=<paste-output-from-openssl>
 ```
 
+Optional override for the embedded Drizzle Studio worker port:
+
+```bash
+# In .env:
+NUXT_DRIZZLE_STUDIO_INTERNAL_PORT=64983
+```
+
+Keep this value private. The app binds the Studio worker to `127.0.0.1` inside the container and proxies it through the authenticated admin UI.
+
 ### 3. Configure Docker Compose
 
 Open the `docker-compose.yml` file and update the Traefik `Host` rule to match your domain:
@@ -74,6 +83,8 @@ docker compose up --build -d
 
 The application will be accessible at your configured domain. Traefik will automatically handle SSL certificate provisioning via Let's Encrypt.
 
+After login, the admin menu includes `/admin/database`, which opens Drizzle Studio inside the app through the protected proxy.
+
 ## Data Persistence
 
 The `docker-compose.yml` mounts one directory:
@@ -89,6 +100,7 @@ The Docker image uses a multi-stage build:
 - The `build` stage installs the full toolchain and runs `nuxt build`.
 - The `production` stage copies only the generated `.output` directory.
 - The container starts `node .output/server/index.mjs` directly.
+- The embedded Drizzle Studio worker is started lazily by Nitro on first access to `/admin/database`.
 
 The final image does not run a second package install step. Nuxt's production build already emits the standalone server output used by the container.
 
@@ -150,6 +162,7 @@ The `docker-compose.yml` file mounts `./.data:/app/.data`. All application data
 - Always set a strong `NUXT_JWT_SECRET` (at least 48 bytes of randomness).
 - Change the default admin password before making the application publicly accessible.
 - The `NUXT_JWT_SECRET` is the only secret passed via environment variable in `docker-compose.yml`. Admin credentials can be set in `.env` and are read by the container at startup.
+- Keep `NUXT_DRIZZLE_STUDIO_INTERNAL_PORT` unset unless you need to avoid a local port clash inside the container runtime.
 - Traefik handles SSL termination. Internal traffic between Traefik and the container is unencrypted (port 3000) but stays within the Docker network.
 
 ## Using a Pre-Built Image
diff --git a/docs/setup-production.md b/docs/setup-production.md
index 9272fe8..3ce365d 100755
--- a/docs/setup-production.md
+++ b/docs/setup-production.md
@@ -56,6 +56,7 @@ Set production values for:
 - `NUXT_ADMIN_USERNAME`
 - `NUXT_ADMIN_PASSWORD`
 - `NUXT_JWT_SECRET`
+- `NUXT_DRIZZLE_STUDIO_INTERNAL_PORT` when you need a non-default private Studio worker port
 
 ## Data Persistence
 
@@ -68,6 +69,7 @@ Set production values for:
 - Check API availability with `/api/questions`.
 - Read container or process logs from stdout.
 - Watch WebSocket connection counts in the admin connection endpoint when needed.
+- Verify `/admin/database` after login if you need database inspection in production.
 
 ## Backup Strategy
 

From 547d0fd5c8b821dce63beb69ae19c87c9d36d786 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:22:00 +0200
Subject: [PATCH 06/12] docs: sync env example defaults

---
 .env.example | 62 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 19 deletions(-)

diff --git a/.env.example b/.env.example
index 08fcb3d..d9e1267 100644
--- a/.env.example
+++ b/.env.example
@@ -1,27 +1,51 @@
-# --- Server-side secrets (not exposed to client)
+# --- Server-side runtime config (not exposed to client)
 
-# Admin Credentials (defaults to admin / 123)
-NUXT_ADMIN_USERNAME=
-NUXT_ADMIN_PASSWORD=
+# Admin login username.
+# Default from nuxt.config.ts: admin
+NUXT_ADMIN_USERNAME=admin
 
-# JWT Secret for Admin Authentication (defaults to tryUJ0zQbstPbTOrezme+Fv+KndzDNRx5lmSeelr2ial2/2yV8HqLeQ2felJafqf)
-NUXT_JWT_SECRET=
+# Admin login password.
+# Default from nuxt.config.ts: 123
+NUXT_ADMIN_PASSWORD=123
 
-# --- Public configuration (available on both client and server)
+# Private internal port for the embedded Drizzle Studio worker.
+# Default from nuxt.config.ts: 64983
+NUXT_DRIZZLE_STUDIO_INTERNAL_PORT=64983
 
-# WebSocket URL for client connections (defaults to current host)
-# NUXT_PUBLIC_WS_URL=ws://localhost:3000
+# JWT secret used for admin authentication.
+# Default from nuxt.config.ts: tryUJ0zQbstPbTOrezme+Fv+KndzDNRx5lmSeelr2ial2/2yV8HqLeQ2felJafqf
+NUXT_JWT_SECRET=tryUJ0zQbstPbTOrezme+Fv+KndzDNRx5lmSeelr2ial2/2yV8HqLeQ2felJafqf
 
-# API URL for client requests (defaults to current host)
-# NUXT_PUBLIC_API_URL=http://localhost:3000
+# --- Public runtime config (available on client and server)
 
-# Server Configuration
-# NUXT_PUBLIC_HOST=0.0.0.0
-# NUXT_PUBLIC_PORT=3000
+# Base API URL used by the client.
+# Default from nuxt.config.ts: empty string, which keeps same-origin requests.
+NUXT_PUBLIC_API_URL=
 
-# Show debug (defaults to false / false)
-# NUXT_PUBLIC_DEBUG_SHOW_WEBSOCKET_CONNECTIONS_IN_FRONTEND=false
-# NUXT_PUBLIC_DEBUG_SHOW_CONSOLE_OUTPUTS=false
+# Toggle console debug output in shared logging helpers.
+# Default from nuxt.config.ts: false
+NUXT_PUBLIC_DEBUG_SHOW_CONSOLE_OUTPUTS=false
 
-# Emoji-Sent Cooldown in Milliseconds (defaults to 1500)
-NUXT_PUBLIC_EMOJI_COOLDOWN_MS=
+# Show websocket connection debug info in the frontend debug panel.
+# Default from nuxt.config.ts: false
+NUXT_PUBLIC_DEBUG_SHOW_WEBSOCKET_CONNECTIONS_IN_FRONTEND=false
+
+# Cooldown in milliseconds between emoji submissions.
+# Default from nuxt.config.ts: 1500
+NUXT_PUBLIC_EMOJI_COOLDOWN_MS=1500
+
+# Public host hint used by the app when building URLs.
+# Default from nuxt.config.ts: 0.0.0.0
+NUXT_PUBLIC_HOST=0.0.0.0
+
+# Public port hint used by the app when building URLs.
+# Default from nuxt.config.ts: 3000
+NUXT_PUBLIC_PORT=3000
+
+# Public version string exposed to the client.
+# Default from nuxt.config.ts: current package version.
+NUXT_PUBLIC_VERSION=1.0.0-rc.0
+
+# Base websocket URL used by the client.
+# Default from nuxt.config.ts: empty string, which keeps same-origin websocket resolution.
+NUXT_PUBLIC_WS_URL=

From 98e41561f501e62110e96158a5a59f17efa63007 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:40:44 +0200
Subject: [PATCH 07/12] fix: harden drizzle studio asset proxy fetch

---
 .../drizzle-studio/app/[...asset].get.ts      | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/server/api/admin/drizzle-studio/app/[...asset].get.ts b/server/api/admin/drizzle-studio/app/[...asset].get.ts
index 1482d04..03b5b7a 100644
--- a/server/api/admin/drizzle-studio/app/[...asset].get.ts
+++ b/server/api/admin/drizzle-studio/app/[...asset].get.ts
@@ -1,6 +1,7 @@
 import { verifyAdmin } from '../../../../utils/auth'
 
 const DRIZZLE_STUDIO_APP_ORIGIN = 'https://local.drizzle.studio'
+const DRIZZLE_STUDIO_ASSET_FETCH_TIMEOUT_MS = 8000
 const FORWARDED_HEADERS = [
   'cache-control',
   'content-type',
@@ -22,7 +23,24 @@ export default defineEventHandler(async (event) => {
 
   const requestUrl = getRequestURL(event)
   const upstreamUrl = `${DRIZZLE_STUDIO_APP_ORIGIN}/${assetPath}${requestUrl.search}`
-  const response = await fetch(upstreamUrl)
+  let response: Response
+
+  try {
+    response = await fetch(upstreamUrl, {
+      signal: AbortSignal.timeout(DRIZZLE_STUDIO_ASSET_FETCH_TIMEOUT_MS),
+    })
+  }
+  catch (error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError'
+
+    throw createError({
+      statusCode: isAbort ? 504 : 502,
+      statusMessage: isAbort
+        ? `Timed out loading Drizzle Studio asset: ${assetPath}`
+        : 'Failed to reach Drizzle Studio asset upstream',
+      data: error instanceof Error ? { message: error.message } : undefined,
+    })
+  }
 
   if (!response.ok) {
     throw createError({

From 9ff013755d3793fc04c35dfdd002c1825c3b1e18 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:41:21 +0200
Subject: [PATCH 08/12] fix: harden drizzle studio html sanitization

---
 .../api/admin/drizzle-studio/app/index.get.ts | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/server/api/admin/drizzle-studio/app/index.get.ts b/server/api/admin/drizzle-studio/app/index.get.ts
index c49ee1b..105b6ca 100644
--- a/server/api/admin/drizzle-studio/app/index.get.ts
+++ b/server/api/admin/drizzle-studio/app/index.get.ts
@@ -4,12 +4,21 @@ const DRIZZLE_STUDIO_APP_ORIGIN = 'https://local.drizzle.studio'
 
 /** Removes third-party analytics from the upstream Studio shell. */
 function sanitizeStudioHtml(html: string) {
-  const analyticsScript = new RegExp(
-    '<script defer="defer" data-site-id="local\\.drizzle\\.studio" '
-    + 'src="https:\\/\\/assets\\.onedollarstats\\.com\\/stonks\\.js"><\\/script>',
-  )
+  const scriptTagPattern = /<script\b[^>]*>[\s\S]*?<\/script>/gi
+
+  return html.replace(scriptTagPattern, (scriptTag) => {
+    const normalizedTag = scriptTag.toLowerCase()
+
+    if (
+      normalizedTag.includes('assets.onedollarstats.com/stonks.js')
+      || normalizedTag.includes('data-site-id="local.drizzle.studio"')
+      || normalizedTag.includes("data-site-id='local.drizzle.studio'")
+    ) {
+      return ''
+    }
 
-  return html.replace(analyticsScript, '')
+    return scriptTag
+  })
 }
 
 export default defineEventHandler(async (event) => {

From ce6bd5b1875c1dc8191e45cc767093e43839835b Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:41:49 +0200
Subject: [PATCH 09/12] fix: harden drizzle studio shell fetch

---
 .../api/admin/drizzle-studio/app/index.get.ts | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/server/api/admin/drizzle-studio/app/index.get.ts b/server/api/admin/drizzle-studio/app/index.get.ts
index 105b6ca..765d0b5 100644
--- a/server/api/admin/drizzle-studio/app/index.get.ts
+++ b/server/api/admin/drizzle-studio/app/index.get.ts
@@ -1,6 +1,7 @@
 import { verifyAdmin } from '../../../../utils/auth'
 
 const DRIZZLE_STUDIO_APP_ORIGIN = 'https://local.drizzle.studio'
+const DRIZZLE_STUDIO_SHELL_FETCH_TIMEOUT_MS = 8000
 
 /** Removes third-party analytics from the upstream Studio shell. */
 function sanitizeStudioHtml(html: string) {
@@ -24,7 +25,24 @@ function sanitizeStudioHtml(html: string) {
 export default defineEventHandler(async (event) => {
   await verifyAdmin(event)
 
-  const response = await fetch(`${DRIZZLE_STUDIO_APP_ORIGIN}/`)
+  let response: Response
+
+  try {
+    response = await fetch(`${DRIZZLE_STUDIO_APP_ORIGIN}/`, {
+      signal: AbortSignal.timeout(DRIZZLE_STUDIO_SHELL_FETCH_TIMEOUT_MS),
+    })
+  }
+  catch (error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError'
+
+    throw createError({
+      statusCode: isAbort ? 504 : 502,
+      statusMessage: isAbort
+        ? 'Timed out loading Drizzle Studio shell'
+        : 'Failed to reach Drizzle Studio upstream',
+      data: error instanceof Error ? { message: error.message } : undefined,
+    })
+  }
 
   if (!response.ok) {
     throw createError({

From 238bf09a5d128dc88f3a78122111bb1f52c56b79 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:42:20 +0200
Subject: [PATCH 10/12] fix: bound drizzle studio rpc proxy fetch

---
 server/routes/index.post.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/server/routes/index.post.ts b/server/routes/index.post.ts
index 9bdb774..38da55f 100644
--- a/server/routes/index.post.ts
+++ b/server/routes/index.post.ts
@@ -4,6 +4,8 @@ import {
   getDrizzleStudioInternalRpcUrl,
 } from '../utils/drizzle-studio'
 
+const DRIZZLE_STUDIO_RPC_TIMEOUT_MS = 10000
+
 const FORWARDED_HEADERS = [
   'cache-control',
   'content-type',
@@ -25,6 +27,7 @@ export default defineEventHandler(async (event) => {
   try {
     response = await fetch(getDrizzleStudioInternalRpcUrl(event), {
       method: 'POST',
+      signal: AbortSignal.timeout(DRIZZLE_STUDIO_RPC_TIMEOUT_MS),
       headers: {
         'accept': getHeader(event, 'accept') || 'application/json',
         'content-type': getHeader(event, 'content-type') || 'application/json',
@@ -33,9 +36,13 @@ export default defineEventHandler(async (event) => {
     })
   }
   catch (error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError'
+
     throw createError({
-      statusCode: 502,
-      statusMessage: 'Failed to reach the Drizzle Studio proxy',
+      statusCode: isAbort ? 504 : 502,
+      statusMessage: isAbort
+        ? 'Timed out reaching the Drizzle Studio proxy'
+        : 'Failed to reach the Drizzle Studio proxy',
       data: error instanceof Error ? { message: error.message } : undefined,
     })
   }

From 442afed44566f8aee1251ebfd5702e1d68daa9b0 Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:42:47 +0200
Subject: [PATCH 11/12] fix: bound drizzle studio startup polling

---
 server/utils/drizzle-studio.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/server/utils/drizzle-studio.ts b/server/utils/drizzle-studio.ts
index 899e089..44ac950 100644
--- a/server/utils/drizzle-studio.ts
+++ b/server/utils/drizzle-studio.ts
@@ -6,6 +6,7 @@ import { getLocalDatabasePath } from '../database/local-config'
 const DRIZZLE_STUDIO_INTERNAL_HOST = '127.0.0.1'
 const DEFAULT_DRIZZLE_STUDIO_INTERNAL_PORT = 64983
 const DRIZZLE_STUDIO_STARTUP_TIMEOUT_MS = 15000
+const DRIZZLE_STUDIO_STARTUP_REQUEST_TIMEOUT_MS = 2000
 const DRIZZLE_STUDIO_STARTUP_POLL_MS = 250
 
 declare global {
@@ -40,8 +41,12 @@ async function waitForDrizzleStudio(event: H3Event) {
 
   while (Date.now() < deadline) {
     try {
+      const remainingMs = deadline - Date.now()
       const response = await fetch(url, {
         method: 'POST',
+        signal: AbortSignal.timeout(
+          Math.max(1, Math.min(DRIZZLE_STUDIO_STARTUP_REQUEST_TIMEOUT_MS, remainingMs)),
+        ),
         headers: {
           'accept': 'application/json',
           'content-type': 'application/json',

From e1dcfb00c57a58130fcf51679fef08c43b9bffaa Mon Sep 17 00:00:00 2001
From: Thorsten Seyschab <hello@todde.tv>
Date: Sun, 3 May 2026 20:59:45 +0200
Subject: [PATCH 12/12] fix: validate drizzle studio asset paths

---
 server/api/admin/drizzle-studio/app/[...asset].get.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/server/api/admin/drizzle-studio/app/[...asset].get.ts b/server/api/admin/drizzle-studio/app/[...asset].get.ts
index 03b5b7a..725c175 100644
--- a/server/api/admin/drizzle-studio/app/[...asset].get.ts
+++ b/server/api/admin/drizzle-studio/app/[...asset].get.ts
@@ -21,6 +21,15 @@ export default defineEventHandler(async (event) => {
     })
   }
 
+  const pathSegments = assetPath.split('/')
+
+  if (pathSegments.some(segment => segment === '.' || segment === '..')) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Invalid Drizzle Studio asset path',
+    })
+  }
+
   const requestUrl = getRequestURL(event)
   const upstreamUrl = `${DRIZZLE_STUDIO_APP_ORIGIN}/${assetPath}${requestUrl.search}`
   let response: Response