Web admin app

@bitz/app (apps/app) is the web admin single-page application. It is a Vite + React 19 app whose only data channel is @bitz/platform-sdk, whose only composite-UI source is @bitz/widgets, and whose only styling system is Tailwind CSS v4. Pages compose widgets and call usePlatform().api.<method>(...); they do not fetch, they do not copy DTOs, and they do not hand-roll loading states.

1. Build & dev topology

The dev proxy is the reason local development has zero CORS friction: the browser only ever sees http://localhost:6800, and Vite forwards the API path to the .NET Host. The proxy is itself conditional — it only exists when command === 'serve' && VITE_API_BASE_URL === '', so the same config works for dev-proxy and direct modes.

// An empty API base keeps browser traffic same-origin.
const apiBaseUrl = environment.VITE_API_BASE_URL ?? '';
// Create the proxy only for the dev server when direct mode is off.
const useDevProxy = command === 'serve' && apiBaseUrl === '';

server: {
  port: 6800,
  strictPort: true,
  ...(useDevProxy
    ? {
        proxy: {
          '/api':    { target: environment.VITE_PROXY_TARGET ?? 'http://localhost:6881', changeOrigin: false },
          '/health': { target: environment.VITE_PROXY_TARGET ?? 'http://localhost:6881', changeOrigin: false },
          // SignalR negotiate + WebSocket must stay same-origin; /hubs gets ws forwarding.
          '/hubs':   { target: environment.VITE_PROXY_TARGET ?? 'http://localhost:6881', changeOrigin: false, ws: true },
        },
      }
    : {}),
}

2. Environment variables

3. Runtime composition

The app assembles a small, fixed set of libraries:

4. Entry, providers, and routing

main.tsx wires the provider tree in a fixed order: StrictMode > PlatformProvider(config) > WorkspacePreferencesProvider(injecting safe first-paint brand/colorMode/density/shellPreset defaults) > QueryClientProvider > PrincipalQueryCacheBoundary > RouterProvider + AppToaster. Mount point is #root. There is no root I18nProvider — pages opt into i18n where needed.

Routing lives in src/routes.tsx. Routes extend React Router’s RouteObject with meta (requiresAuth?, permission?, title?) and a string lazy that normalizeRoutes converts to a lazyRoute() glob import:

RouteGuard is the route-level gate (complementing the button-level PermissionGate widget). It reads meta.requiresAuth and meta.permission and redirects to /login when unauthenticated or unauthorized. A RouteLoading HydrateFallback covers lazy-chunk fetches.

5. The widget layer

Pages compose from @bitz/widgets, which hides the glue that every data screen otherwise rewrites:

ServerDataTable<T> props

The widget itself does not touch URLSearchParams — the page owns URL state (see users-list.tsx, which keys params page/size/q/status/sort/order). State machine: isLoading → QueryState; isError or data.ok === false → ErrorState (prefers the PlatformFailure.error, falls back to mapping the thrown error); empty items → EmptyState; else the table with a “N total · page X of Y” pagination footer.

Shell and notifications

AppShell reads the deployment-level VITE_SHELL_PRESET:

• side: a 64px module rail plus a 176px current-module panel, with bounded desktop resizing;
• top: both the primary bar and the context bar take their height from the density token --cmp-shell-header-height (48px dense / 56px compact / 64px comfortable+), not hard-coded pixels; primary entries beyond capacity move into “More”, while narrow screens receive a complete module menu;
• both layouts share one api.getNavigation() query, URL model, permission model, and page recipe.

Identity module routes are rendered once by the Shell. Pages use WorkspaceLocalTabs only for genuine content partitions; while scrolling, Local Tabs stick below the fixed Shell rows, and the title plus primary actions move into the existing Global bar.

The HeaderBar notification entry calls getNotificationInbox, getNotificationUnreadCount, markNotificationRead, and markAllNotificationsRead. These methods bridge generated OpenAPI types, and notification URLs accept only normalized same-origin absolute paths. Search, help, or theme buttons are not rendered as dead controls before they have real owners.

FormField props

Uses useId() to link htmlFor/id. No built-in validation engine — errors are passed in.

ConfirmAction props

Buttons disable while onConfirm is in flight; the dialog closes only after the promise resolves.

6. Permission-aware UI (two levels)

Permission gating happens at two layers, both UX-only:

import { PermissionGate } from "@bitz/widgets";

<PermissionGate require="identity.user.search" showFallback>
  {/* the whole users page */}
</PermissionGate>;

• Route-level: RouteGuard reads meta.permission from routes.tsx and redirects unauthorized users.
• Button-level: the PermissionGate widget hides/enables UI based on currentUser?.permissions.

Both read the same permission set, which comes from /api/auth/me — never from localStorage. The backend must enforce the same capabilities in its authorization pipeline.

7. Seed screens

These exist so the platform-sdk contract and the widget composition have working examples; extending the admin app means adding routes that follow the same composition pattern.

8. PWA configuration

config/pwa-options.ts configures vite-plugin-pwa: registerType: 'prompt', injectRegister: false, manifest name/short_name: 'FD WORK', display: 'standalone', start_url: '/', two SVG icons (any + maskable). Workbox precaches **/*.{js,mjs,css,html,svg,png,ico,jpg,webp} (no mp4 — large media such as the sign-in video stays out of the precache) up to 10 MB, with cleanupOutdatedCaches and clientsClaim on; skipWaiting: false (the prompt registration flow controls activation). /web/viewer.html* is in navigateFallbackDenyList.

9. Path aliases

apps/app/tsconfig.json extends tsconfig.base.json and maps @/* → ./src/*, plus the @bitz/components, @bitz/i18n, and @bitz/platform-sdk package roots. The remaining @bitz/* resolutions (widgets, editor, hooks, utils, materials, scripts) come from tsconfig.base.json, which maps every workspace package.

10. Reviewing a web-app change

1. Confirm any new HTTP call goes through usePlatform().api — not a page-level fetch.
2. Confirm every new backend type is imported from @bitz/platform-sdk and ultimately aliases a generated schema — never hand-written.
3. If a new data screen is added, prefer composing @bitz/widgets (ServerDataTable, QueryState) over rewriting the states.
4. If a new route is added, give it meta.requiresAuth / meta.permission so RouteGuard enforces it.
5. Run yarn workspace @bitz/app build before commit — tsc --noEmit runs first and fails on type errors, and the bundle must pass the verify-bundle-budget.mjs size gate.

11. Source review

# Confirm pages consume the SDK through context and widgets through the barrel.
rg -n "usePlatform|from '@bitz/widgets'|from '@bitz/platform-sdk'" \
  frontend/apps/app/src/pages

# Confirm the provider tree order and the conditional dev proxy.
sed -n '1,40p' frontend/apps/app/src/main.tsx
sed -n '1,70p' frontend/apps/app/vite.config.ts

# Confirm routing meta and RouteGuard wiring.
rg -n "requiresAuth|permission|RouteGuard" frontend/apps/app/src/routes.tsx

Back to Frontend · Platform contract layer · Mobile shell