Frontend & UI Review + Improvement Plan

Document: FRONTEND_UI_IMPROVEMENT_PLAN.md Scope: miz-oki-command-center-ui/ (Command Center UI — the primary operator frontend), with reference notes on apps/web/ and the # MIZ OKI 3.5/ marketing site Date: August 5, 2026 Status: Review complete — plan proposed, not yet executed Claim label: All figures below are measured results from the repository at the time of review unless labeled otherwise.

Table of Contents

1. Executive Summary
2. What Was Reviewed
3. Current-State Architecture
4. Backend Wiring Assessment
5. Best-Practices Conformance Scorecard
6. Key Findings (Ranked by Severity)
7. Target Architecture
8. Improvement Plan — Phases 0–5
9. UX / Ease-of-Use Redesign
10. Expansion Opportunities
11. Risk Register & Rollout Strategy
12. Success Metrics
13. Appendix A — Measured Inventory

1. Executive Summary

The Command Center UI is a very large, feature-rich Next.js application (155 pages, 210 API routes, 243 components, 65 hooks, 135 lib modules) that is genuinely well-wired into the backend fleet: it has a real BFF (backend-for-frontend) layer of Next.js API routes that proxy to Cloud Run services with OIDC authentication, SSE streaming, Zustand global state, React Query, and OpenTelemetry instrumentation. This is far beyond a typical dashboard scaffold.

However, the app has accumulated significant structural and quality debt that undermines its strengths:

Bottom line: the plumbing is real and mostly good; the airframe needs consolidation. The plan below is sequenced so that the safety net comes first (types, lint, tests, CI gates), consolidation second (dead route removal, single API client, config-driven URLs), and UX/expansion third — because refactoring 155 pages without tests or type checking is how regressions ship silently. This ordering matters more than any individual item.

2. What Was Reviewed

2.1 Frontend surfaces in the monorepo

This plan targets the Command Center UI. The marketing site is governed by the design-canon lock and must not be touched by this effort.

2.2 Measured inventory (Command Center UI)

3. Current-State Architecture

3.1 System context

flowchart LR
    subgraph Browser
        UI[Command Center UI<br/>Next.js 15 / React 19<br/>311 client components]
    end

    subgraph "Next.js server (Cloud Run: miz-oki-command-center-ui)"
        BFF[210 API routes<br/>BFF / OIDC proxy layer]
        MW[middleware.ts<br/>Supabase session refresh]
        OTEL[instrumentation.ts<br/>OpenTelemetry]
    end

    subgraph "Cloud Run backend fleet (us-central1)"
        BOSS[boss-agent-adk<br/>1,137+ MCP tools]
        MOA[miz-oki-moa-controller]
        MOE[miz-oki-moe-router]
        CELLS[36 cells<br/>cell01..cell32 + ORACLE 33-36]
        GOV[10 service-* governance services]
    end

    subgraph "Data plane"
        FS[(Firestore<br/>28+ collections)]
        BQ[(BigQuery)]
        NEO[(Neo4j KG)]
        SB[(Supabase Auth)]
        FB[(Firebase)]
    end

    UI -->|fetch /api/*| BFF
    UI -.->|"391 hardcoded run.app URLs (bypass ⚠️)"| CELLS
    UI <-->|SSE / Socket.io| BFF
    BFF -->|OIDC identity tokens| BOSS
    BFF -->|OIDC| MOA & MOE
    BFF -->|"same-origin /api/orchestration proxy"| CELLS
    BOSS --> FS & BQ & NEO
    MW --> SB
    BFF --> FB

The critical wiring flaw is the dotted line: since the Phase-8 IAM lockdown (see CLAUDE.md MIZ-FIN-2026-005), browser code cannot mint Cloud Run OIDC tokens, so every one of the 391 direct *.run.app references in client code is either (a) hitting one of the shrinking set of intended-public services, (b) silently failing with 403, or (c) working only until that service gets IAM-locked. The repo's own records confirm this failure class ("Browser callers cannot mint Cloud Run OIDC — health/widgets against IAM-locked services need a same-origin nodejs proxy"). The BFF pattern already exists (app/api/orchestration/[svc]/[...path]) — it just isn't used consistently.

3.2 Frontend internal architecture (as-is)

flowchart TD
    subgraph "app/ — 87 top-level route groups, 155 pages"
        LAYOUT["layout.tsx<br/>force-dynamic ⚠️<br/>headers()-based auth-route check"]
        PAGES[Feature pages<br/>dashboard, boss, agents, kg,<br/>campaigns, cells, channels ...]
        DEAD["16 app/boss* dirs<br/>7 archived variants still shipped ⚠️"]
        API[210 API routes]
    end

    subgraph "State & data"
        STORE[Zustand store<br/>10 files: slices for agents,<br/>kernels, realtime, ui, workflows]
        RQ[React Query<br/>QueryClientProvider]
        SSE[useSSE / useMultiSSE<br/>global stream in providers.tsx]
        POLL["setInterval polling in providers.tsx<br/>1m / 2m / 5m ⚠️ redundant with SSE"]
    end

    subgraph "lib/ — 135 modules"
        CLIENTS["Multiple overlapping API clients ⚠️<br/>api-service.ts, cloud-run-client.ts,<br/>a2a-client.ts, boss-*-client(s), ..."]
        AUTHZ[supabase/server.ts + client.ts<br/>firebase-client.ts, jwt.ts]
        TEL[telemetry.ts withToolSpan]
        SAFE[safe-navigation.ts toSafeUrl]
    end

    LAYOUT --> PAGES
    PAGES --> STORE & RQ
    PAGES -->|"direct fetch/axios in components ⚠️"| API
    STORE --> SSE
    STORE --> POLL
    PAGES --> CLIENTS
    CLIENTS --> API

Notable as-is properties:

• Two provider files exist (app/providers.tsx and components/providers.tsx referenced from app/layout.tsx) — a duplication that makes it unclear which provider tree is authoritative.
• providers.tsx runs three setInterval polls (kernels 1m, workflows 2m, agents 5m) and opens a global SSE stream — double-fetching the same classes of data.
• export const dynamic = 'force-dynamic' in the root layout disables static optimization for the entire app, because the layout calls headers() for auth-route detection — a check that belongs in middleware.ts (which already exists).
• State is split three ways (Zustand, React Query, ad-hoc useState+fetch in components) with no documented rule for which owns what.

4. Backend Wiring Assessment

4.1 What is genuinely good

4.2 Where the wiring is broken or fragile

4.3 Verdict

Wiring quality is bimodal: the server-side BFF/OIDC/streaming layer is production-grade; the client-side consumption of it is undisciplined. The fix is not new infrastructure — it is funneling all data access through one typed client that only talks to the BFF, and deleting the 391 bypasses.

5. Best-Practices Conformance Scorecard

Assessed against current Next.js 15 / React 19 guidance (App Router, Server Components, streaming, typed APIs) and general frontend engineering practice.

Score: 2 ✅ / 6 ⚠️ / 9 ❌. The app is modern in framework version but not in framework usage.

6. Key Findings (Ranked by Severity)

🔴 Critical

F1 — The safety net is disarmed. strict: false + ignoreBuildErrors + ignoreDuringBuilds + zero tests means the only thing standing between a bad change and production is a successful next build. The repo's own history proves the cost: the UI carried a ~556-error TypeScript baseline, a broken SSE endpoint, and a fetch served by no route — all shipped under green CI. Every other improvement in this plan is unsafe to execute until this is fixed.

F2 — 391 hardcoded backend URLs in a fleet that is being IAM-locked. The platform is actively removing public access from services (Phase-8 waves, 47 services flipped to ingress=all + IAM). Browser code cannot mint OIDC tokens. Every hardcoded client-side run.app call is a latent 403.

F3 — Stateful API routes on stateless infrastructure. The in-memory conversationMemory Map in app/api/boss/chat/route.ts (and any similar module-level state) loses data on scale-down and splits sessions across instances. The file's own comment says "replace with Redis/DB in production" — it is in production.

🟠 High

F4 — Dead weight shipped to users. 7 archived app/boss-* variants, duplicated provider trees, and 4 overlapping graph-visualization libraries inflate build time, bundle size, and cognitive load. 155 pages is likely 2–3× the number of pages operators actually use.

F5 — Server-rendering benefits thrown away. force-dynamic on the root layout + near-universal 'use client' means Next.js is being used as an SPA host with extra steps. The auth-route check that forces this belongs in middleware.

F6 — No state-ownership rules. Zustand slices, React Query, SSE stream, polling intervals, and component-local fetches all manage overlapping data. This produces stale-data bugs and makes every new feature a judgment call.

🟡 Medium

F7 — Missing UX conventions. No root loading.tsx/not-found.tsx/global-error.tsx; loading/empty/error states are hand-rolled per page and inconsistent; no skeleton system.

F8 — Navigation overload. ~87 top-level route groups surface in an app with a sidebar that must enumerate them. There is no progressive disclosure, no per-role landing experience, and command-palette (cmdk is installed!) is not wired as the universal navigator.

F9 — Dependency risk. pydantic (a Python package) is listed in package.json dependencies; react-json-view is React-18-era; AI SDKs (openai, @anthropic-ai/sdk, langchain) in the client dependency graph invite accidental client-side key usage.

7. Target Architecture

7.1 Data-flow after the plan

flowchart LR
    subgraph Browser
        RSC[Server Components<br/>initial data, static shells]
        CC[Client components<br/>interactivity only]
        HOOKS[Typed hooks<br/>useQuery / useMutation]
    end

    subgraph "Next.js server"
        GW["lib/api/gateway.ts<br/>ONE typed client<br/>(zod-validated, env-driven)"]
        BFFX[Consolidated BFF routes<br/>~120 after dedup]
        KV[(Redis / Firestore<br/>session + conversation state)]
    end

    subgraph Backend
        FLEET[Cloud Run fleet<br/>OIDC-locked]
    end

    RSC --> GW
    CC --> HOOKS --> BFFX
    BFFX --> GW
    GW -->|OIDC, retries, tracing| FLEET
    BFFX --> KV

    style GW fill:#0a5,stroke:#333,color:#fff

Rules encoded by this architecture (enforced by ESLint, not convention):

1. Zero run.app strings outside lib/config/services.ts. One env-driven registry; a lint rule bans the literal elsewhere.
2. Browser code talks only to same-origin /api/*. The BFF is the only path to the fleet.
3. Server state lives in React Query; UI state lives in Zustand; nothing lives in module scope.
4. SSE invalidates React Query caches instead of polling — one source of truth, real-time by default.

7.2 Route information architecture (target)

flowchart TD
    ROOT["/ — Role-aware home"]
    ROOT --> OPS["(operations)/<br/>dashboard, cells, health, deployments"]
    ROOT --> AGENTS["(agents)/<br/>boss, agent-ide, moa-moe, launcher"]
    ROOT --> INTEL["(intelligence)/<br/>kg, causal, oracle-intent, analytics"]
    ROOT --> MKTG["(marketing)/<br/>campaigns, channels, creatives, attribution"]
    ROOT --> ADMIN["(admin)/<br/>settings, auth, api-keys, audit"]
    ROOT --> CMDK[["⌘K command palette<br/>universal navigation + actions"]]

    style CMDK fill:#7c3aed,color:#fff

87 flat directories become 5 route groups + a command palette. Archived variants are deleted (they remain in git history). Every page inside a group inherits the group's layout, breadcrumbs, and loading/error conventions.

8. Improvement Plan — Phases 0–5

Sequenced by dependency: each phase makes the next one safe. No calendar estimates; effort is characterized by invasiveness.

Phase 0 — Safety net (low-invasiveness, highest leverage)

Exit gate: CI red on any new type/lint error; ≥30 tests passing; conventions present.

Phase 1 — Wiring correctness (medium invasiveness)

Exit gate: grep -r "run.app" app/ components/ hooks/ lib/ --include='*.ts*' returns only lib/config/services.ts; chat memory survives instance restarts (verified by test).

Phase 2 — Consolidation & dead-code removal (medium-high invasiveness)

Exit gate: page count reduced ≥25%; bundle size reduced (measured via @next/bundle-analyzer added in this phase); no route 404s in the E2E crawl.

Phase 3 — Rendering & performance (high invasiveness, incremental)

Exit gate: Lighthouse performance ≥85 on dashboard and boss chat (from a measured pre-phase baseline); TS baseline reduced ≥50%.

Phase 4 — UX overhaul (see §9)

Phase 5 — Expansion (see §10)

9. UX / Ease-of-Use Redesign

9.1 Problems observed

1. No progressive disclosure — a new operator faces ~87 nav destinations with equal visual weight.
2. No universal search/actions — cmdk is installed but not surfaced as a global ⌘K palette across pages.
3. Inconsistent feedback — loading, empty, and error states differ per page; some pages render blank while fetching.
4. No role-aware entry — an analyst, a media buyer, and a platform operator all land on the same home.
5. Real-time is invisible — SSE data updates silently; there's no connection-status affordance or "live" indicators.

9.2 Redesign pillars

flowchart LR
    P1["1. Command Palette<br/>⌘K everywhere:<br/>navigate, run MCP tools,<br/>ask Boss"] --> UX((Operator<br/>Experience))
    P2["2. Role-aware Home<br/>3 presets: Operator,<br/>Analyst, Media Buyer"] --> UX
    P3["3. Unified feedback<br/>skeletons, empty states,<br/>error boundaries, toasts —<br/>one component kit"] --> UX
    P4["4. Live-status system<br/>SSE connection badge,<br/>freshness timestamps,<br/>optimistic mutations"] --> UX
    P5["5. Design tokens +<br/>component docs<br/>(Storybook or Ladle)"] --> UX

Concrete deliverables:

10. Expansion Opportunities

Ordered by value-to-effort once the foundation phases are done:

11. Risk Register & Rollout Strategy

Rollout: every phase lands as a series of small PRs on main behind the CI gates from Phase 0. No big-bang branch. The dashboard and boss-chat pages get canary attention (manual verification) on every consolidation PR since they are the highest-traffic surfaces.

12. Success Metrics

Appendix A — Measured Inventory

All values measured directly from the working tree on the review date.

miz-oki-command-center-ui/
├── app/            155 page.tsx · 210 route.ts · ~87 top-level dirs
│   ├── boss*       16 directories (7 archived variants)
│   ├── error.tsx   ✅ present
│   ├── loading.tsx ❌ missing   not-found.tsx ❌ missing   global-error.tsx ❌ missing
├── components/     243 files (incl. duplicate providers.tsx vs app/providers.tsx)
├── hooks/          65 files (useSSE, useMultiSSE, useBossAgentChat, useCellStatus, ...)
├── lib/            135 files (api-service, cloud-run-client, a2a-client, supabase/,
│                   firebase-client, telemetry, safe-navigation, edge-inference/, ...)
├── store/          10 files (Zustand slices: agents, kernels, realtime, ui, workflows)
├── middleware.ts   ✅ Supabase session refresh
├── instrumentation.ts ✅ OpenTelemetry boot
├── next.config.mjs ⚠️ eslint.ignoreDuringBuilds + typescript.ignoreBuildErrors
├── tsconfig.json   ⚠️ strict:false · target:es2015 · skipLibCheck:true
├── .eslintrc.json  ✅ navigation-safety rules (neutralized in builds)
└── tests           ❌ none (jest deps installed, unconfigured)

Key versions (package-lock.json):
  next 15.5.21 · react 19.2.7 · typescript 5.x · node engine unpinned (env: v22.14.0)

Cross-cutting measurements:
  'use client' occurrences ........ 311
  hardcoded *.run.app references ... 391
  known TS error baseline .......... ~556 (per repo delta-tsc records)

Related repo documents

• docs/reports/FRONTEND_UI_GAP_ANALYSIS_2026-07-23.md — earlier gap analysis (superseded by this plan's inventory)
• docs/reports/FRONTEND_INTEGRATION_GUIDE.md — BFF/integration reference
• docs/reports/FRONTEND_MOCK_FIXES.md — prior mock-data cleanup record
• CLAUDE.md — platform source of truth (IAM lockdown waves, SRDAL→SRPVDAL route migrations, delta-tsc baseline practice, design-canon lock on the marketing site)

End of plan. This document proposes changes only; no application code was modified as part of this review.