Blinkin Legacy Docs Docs
Porting · porting/2026-05-05-zweistein-admin-local-runtime.md Docs Home

Zweistein Admin Local Runtime Slice

Date: 2026-05-05

Objective

Make the imported legacy zweistein/admin frontend reproducible locally and prove that it can reach the local Zweistein server through the Vite proxy.

This is a frontend runtime proof, not a full authenticated product flow.

What Was Added

  • configs/local/zweistein-admin.env.example Local-only Vite values for the admin base path, feature flags, and mkcert behavior.
  • scripts/zweistein-admin-local.mjs Small helper for install, Dockerfile-near build, strict legacy typecheck, local dev, and health checks.
  • package.json scripts:
    • zweistein-admin:install
    • zweistein-admin:build
    • zweistein-admin:typecheck
    • zweistein-admin:dev
    • zweistein-admin:health
  • legacy-src/zweistein/admin/vite.config.ts Local dev now only enables vite-plugin-mkcert when VITE_ENABLE_MKCERT=true.

The helper prefers Homebrew node@20 when available, because the legacy Dockerfile uses Node 20.

Local Commands

Start the local Zweistein server first:

npm run zweistein-server:start

Install admin dependencies:

npm run zweistein-admin:install

Build the admin app with the same practical build path used by the legacy Dockerfile:

npm run zweistein-admin:build

Start the admin dev server:

npm run zweistein-admin:dev

In another terminal, check the admin HTML route:

npm run zweistein-admin:health

Expected result:

Zweistein admin dev server responded on http://127.0.0.1:5176/ai/

Check the Vite proxy to the local backend:

curl -fsS http://127.0.0.1:5176/ai/api/authz/config

Expected current response uses local placeholders:

{
  "auth0_domain": "local.invalid",
  "auth0_clientId": "local-client",
  "auth0_audience": "local-audience",
  "featureFlags": {}
}

Verification Evidence

  • npm run zweistein-admin:install completed with Yarn 1.22.22 and warnings only.
  • npm run zweistein-admin:build passed through the Vite build path.
  • npm run zweistein-admin:dev launched the app on http://127.0.0.1:5176/ai/.
  • npm run zweistein-admin:health returned HTTP 200 for the admin HTML route.
  • curl -fsS http://127.0.0.1:5176/ai/api/authz/config returned the backend Auth0 placeholder config through the Vite proxy.

Important Findings

The legacy package has two different build meanings:

  • npm run zweistein-admin:build in this rebuild project runs the Dockerfile-near vite build path and passes.
  • npm run zweistein-admin:typecheck runs the package's strict tsc -b && vite build path and currently fails on legacy TypeScript debt.

The strict typecheck failure is not caused by the local wrapper. It reflects existing code health issues in the imported snapshot, including:

  • a non-exported StripeProvider import in RootProviders.tsx;
  • many unused imports and variables reported by TypeScript;
  • missing @types/file-saver;
  • missing or mismatched ModelTokenDetails enum values;
  • missing plans/interfaces/QuotaDefinition;
  • type mismatches in chat, agentic apps, plans, and controls code.

This means the frontend can be locally served and bundled, but the codebase is not yet clean enough for strict TypeScript-gated CI.

Why mkcert Was Disabled By Default

vite-plugin-mkcert tried to install a local trusted certificate during dev startup. On this machine that requires an interactive sudo password prompt, which is not suitable for the local rebuild helper.

The new local default is:

VITE_ENABLE_MKCERT=false

For a developer who wants local HTTPS and can approve the certificate prompt manually, it can be enabled with:

VITE_ENABLE_MKCERT=true

Not Yet Done

  • Auth0 login was not exercised with real tenant credentials.
  • Authenticated admin pages were not walked in the browser.
  • Stripe, LLM, storage, document, and workflow flows were not tested from the admin UI.
  • Strict TypeScript cleanup is still outstanding.
  • The admin app is not containerized in the new project yet.
  • The admin app is not wired to the future Hetzner public domain yet.