From Monolith to Micro‑Frontend: The Evolution and Refactoring of the Xingyun Frontend Platform

The Xingyun 2.0 era turned a modest business project into a sprawling ecosystem of dozens of sub‑applications built on Vue, sharing a global Vue instance, router, Vuex, component library, and axios.

Architectural dilemmas emerged:

1. Chaotic code structure: The /modules directory was intended for domain‑specific code, but cross‑module component imports created tangled dependencies that broke when any module changed.

2. Business entanglement: A single monolithic repo handled both platform foundations and diverse business features, causing high coupling and domino‑effect failures.

3. Full‑build pain: Frequent releases (every 2‑3 weeks) triggered whole‑repo builds, leading to repeated white‑screen crashes.

4. Commercialization friction: Customers demanded selective code delivery, but the lack of clear boundaries forced manual code pruning.

5. Internal iteration gap: Migration from JavaScript to TypeScript and Vue 2.6 → 2.7 introduced compatibility issues and multi‑repo divergence.

6. Static resource bloat: Shared dependencies could not be stripped, inflating bundle size.

7. Abandoned components: Legacy UI components lingered in the repository, increasing maintenance overhead.

8. Atomic‑style chaos: Inconsistent use of utility‑first classes (e.g., w‑24px vs w‑6) and mixed BEM naming made style management inefficient.

9. New‑business expansion difficulty: Adding features risked breaking UI consistency, increasing build time, and violating the open‑closed principle.

10. Vue CLI limitations: The single build tool became a bottleneck as the codebase grew, causing slow starts and unnecessary recompilations.

Despite these pains, the team decided to persist, recognizing that doing the right thing was worthwhile.

Breakthrough – “Inner‑Outer Same‑Origin” plan: A series of brainstorming sessions produced the "Kill‑Switch" strategy, a gradual replacement pattern where a new system incrementally takes over the old one, reducing risk.

Refactor goals:

1. Module separation – isolate platform code from business code. 2. Build slimming – only build the changed sub‑application. 3. Code cleanup – remove dead components and redundant code. 4. Atomic‑style standardization – unify Tailwind usage. 5. Upgrade extensibility and maintainability via layered architecture. 6. Apply the Kill‑Switch mode for phased migration.

Architecture evolution roadmap:

Stage 1 – Monorepo preparation: Convert the existing repo to a pnpm workspace‑based monorepo, create directory layout, introduce Nx, and update CI/CD.

Stage 2 – Monorepo implementation: Split business modules into independent apps under apps/ (admin, ai‑assistant, jacp, open, platform). Extract shared libraries into packages/ (common, common‑service, components, tailwind‑config, utils, xingyun‑elements). Migrate from Windi CSS to Tailwind CSS and centralize its configuration.

Stage 3 – Automated build pipeline: Use Vue‑CLI/Vite for business apps and Vite/tsup for shared packages, optimise dependency graph, and create release scripts.

Post‑refactor architecture:

The new structure consists of:

apps/ – independent applications each with its own router, state, and UI (admin, ai‑assistant, jacp, open, platform). packages/ – reusable modules: common (shared Vue environment), common‑service (API utilities), components (UI library), tailwind‑config , utils , and xingyun‑elements (web components).

Technical stack: Vue.js, Nx for monorepo management, pnpm as package manager, Tailwind CSS for styling, Vue‑CLI/Vite for builds, TypeScript and ESLint for quality.

Design principles: modularity, micro‑frontend, component‑driven development, theme customization, incremental builds via Nx, and strict type‑checking.

Module responsibilities: Each app is self‑contained; shared packages provide common services, UI components, and utilities.

Development optimizations: Migration of some projects to Vite, caching strategies, parallel build steps, and micro‑frontend tooling to simplify sub‑app debugging.

Cloud build & caching: Code‑splitting, Webpack dynamic imports, Nx cache, and image‑based caching on the deployment platform accelerate build and deployment.

Extensibility: Adding new apps or shared modules follows the open‑closed principle, requiring only a new folder and Nx workspace entry.

Summary: By moving from a monolithic Vue project to a modular monorepo with micro‑frontend architecture, the Xingyun frontend now enjoys clearer boundaries, faster incremental builds, reduced bundle size, consistent styling, and better scalability, providing a solid foundation for future business growth.