Cloud Admin Refactor Notes

Summary

This refactor split the Harbor Cloud Admin app into smaller modules without intentionally changing user-facing behavior or the generated dist/site output shape.

The main goals were:

• reduce the giant browser controller entrypoint
• separate support-console logic from theme-workbench logic
• separate static-site rendering from the build bootstrap
• remove unused React/TSX baggage from a non-React app

What moved where

Browser app modules

- now only boots the browser app

- main browser bootstrap

- admin/session/theme payload types

- shared mutable runtime state

- cloud API and session-storage config

- token storage and authenticated request wrapper

- DOM helpers, feedback helpers, view switching, and generic formatting

- support-console rendering, lookup flows, overrides, notifications, auth/session handling, and password changes

- theme palette generation, preview rendering, theme load/save flow, and theme form binding

• apps/cloud-admin/src/admin-client.ts
• apps/cloud-admin/src/admin/main.ts
• apps/cloud-admin/src/admin/types.ts
• apps/cloud-admin/src/admin/state.ts
• apps/cloud-admin/src/admin/config.ts
• apps/cloud-admin/src/admin/api.ts
• apps/cloud-admin/src/admin/dom.ts
• apps/cloud-admin/src/admin/supportConsole.ts
• apps/cloud-admin/src/admin/theme.ts

Shared app helpers

- shared font option metadata used by both the browser theme editor and the static site builder

• apps/cloud-admin/src/shared/themeTypography.ts

Static site builder

- now only boots the static site build

- file-copy/build orchestration

- shared HTML shell and CSS

- page body markup

- now stores website contact submissions and exposes them to the Cloud Admin support console

• apps/cloud-admin/src/build-site.ts
• apps/cloud-admin/src/site/buildSite.ts
• apps/cloud-admin/src/site/renderLayout.ts
• apps/cloud-admin/src/site/renderBody.ts
• apps/cloud-api

Intentional deviations

• The app still uses direct DOM updates rather than moving to a framework. This refactor keeps the current rendering model and focuses on structure, not a technology change.
• supportConsole.ts is still a fairly large module because the account/enrollment/admin workflows are tightly related and share runtime state.
• renderLayout.ts remains sizable because the static site CSS is intentionally kept colocated with the generated admin shell for now.
• Contact submissions currently land in the support inbox as stored records only. HARBOR_CONTACT_SEND_EMAIL=false keeps local testing database-only for now.

Optimizations included

• Removed unused react and @types/react dependencies from apps/cloud-admin/package.json.
• Removed the unused JSX compiler setting from apps/cloud-admin/tsconfig.json.
• Eliminated duplicated font option definitions by sharing them between the builder and the theme editor.
• Added a support-console contact inbox fed by cloud_contact_submissions.
• Added shared corporate sitemap links so Cloud Admin, Website, and Docs move like one family of Harbor surfaces.

Remaining follow-up

1. If Cloud Admin grows substantially again, split supportConsole.ts into render and action modules.
2. Consider moving repeated static-site CSS patterns into shared theme/layout helpers if Website and Docs need the same treatment next.
3. If the public/admin static surfaces converge further, extract more cross-site builder helpers after refactoring website and docs-site.

Validation

• pnpm --filter @harbor/cloud-admin typecheck
• pnpm --filter @harbor/cloud-admin build