vitepress-template

Appearance

Frontend Applications ​

**Referenced Files in This Document** - [[ui-web/package.json]](file/ui-web/package.json) - [[ui-web-admin/package.json]](file/ui-web-admin/package.json) - [[ui-web-top/package.json]](file/ui-web-top/package.json) - [[ui-web/next.config.ts]](file/ui-web/next.config.ts) - [[ui-web-admin/next.config.ts]](file/ui-web-admin/next.config.ts) - [[ui-web-top/next.config.ts]](file/ui-web-top/next.config.ts) - [[ui-web/tsconfig.json]](file/ui-web/tsconfig.json) - [[ui-web-admin/tsconfig.json]](file/ui-web-admin/tsconfig.json) - [[ui-web-top/tsconfig.json]](file/ui-web-top/tsconfig.json) - [[ui-crx/manifest.json]](file/ui-crx/manifest.json)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document describes the frontend applications that compose the BI Analysis Platform user-facing surfaces:

  • Tenant Console (ui-web): Business user interface for analytics dashboards and insights.
  • Admin Panel (ui-web-admin): System administration and tenant management interface.
  • Navigation Components (ui-web-top): Portal and navigation utilities used across the platform.
  • Browser Extension (ui-crx): Data collection and analysis helper for end-users.

It explains the Next.js 16 App Router architecture, TypeScript configuration, component organization, ECharts integration, state management with Zustand, responsive design, API consumption patterns, authentication flows, and performance optimization techniques.

Project Structure ​

Each application is a standalone Next.js 16 project configured with TypeScript and Tailwind CSS. They share common patterns:

  • Next.js App Router with route groups and dynamic routes.
  • Environment-driven configuration via rewrites and gateway routing.
  • TypeScript strict mode with bundler module resolution.
  • Tailwind CSS for responsive styling.

Diagram sources

Section sources

Core Components ​

  • Tenant Console (ui-web)

    • Next.js 16 App Router with route groups for dashboards and analysis.
    • TypeScript strict mode and Tailwind CSS for responsive UI.
    • ECharts integration for interactive visualizations.
    • Zustand for global state management.
    • Arco Design for UI components and grid/table libraries.
    • API rewrites to backend services via gateway or direct URLs.

  • Admin Panel (ui-web-admin)

    • Next.js 16 App Router with route groups for system management.
    • Arco Design and optional Plasmic integration for rapid UI building.
    • Environment-specific rewrites to tenant-m, sys, and auth APIs.
    • Allowed development origins for local hot reload and WebSocket connections.

  • Navigation Components (ui-web-top)

    • Next.js 16 App Router with internationalization plugin.
    • Framer Motion and next-themes for animations and theme switching.
    • Utility components for portal navigation and shared layouts.

  • Browser Extension (ui-crx)

    • Manifest V3 with service worker, action popup, options page, and content scripts.
    • Permissions for tabs, downloads, storage, scripting, cookies, and context menus.
    • Content scripts injected on all URLs to collect data and interact with pages.

Section sources

Architecture Overview ​

The frontend apps rely on environment-driven configuration to route API traffic either through a central gateway or directly to backend services. ui-web and ui-web-admin define rewrites for tenant, tenant-m, sys, auth, and other domain APIs. ui-web-top integrates internationalization, while ui-crx operates independently as a browser extension.

Diagram sources

Detailed Component Analysis ​

Tenant Console (ui-web) ​

  • Next.js App Router
    • Uses route groups and dynamic segments for dashboards and analysis views.
    • Environment variable controls app environment and configuration selection.
  • TypeScript
    • Strict mode enabled with bundler module resolution and path aliases.
  • UI Libraries
    • Arco Design for components, ECharts for visualizations, ag-Grid for tables, Zustand for state.
  • API Consumption
    • Rewrites proxy requests to tenant, tenant-m, analytics, basic, sys, auth, notify, note, collect, platform-callback, taoxi, bi_api_jushuitan, and bi_leke APIs.
  • Authentication
    • Auth API rewrites support login and RBAC flows; integrate JWT tokens and session management in pages and layout wrappers.
  • State Management
    • Zustand stores global selections, filters, and dashboard state.
  • ECharts Integration
    • Charts rendered with responsive dimensions and theme-aware color palettes.
  • Responsive Design
    • Tailwind utilities and component-level breakpoints ensure mobile-friendly layouts.

Diagram sources

Section sources

Admin Panel (ui-web-admin) ​

  • Next.js App Router
    • Route groups for system management, tenant-m, and auth-related screens.
  • TypeScript
    • Strict mode with bundler module resolution and path aliases.
  • UI Libraries
    • Arco Design and optional Plasmic for rapid UI composition.
  • API Consumption
    • Rewrites to tenant-m, sys, and auth APIs; supports gateway mode for centralized routing.
  • Development Origins
    • Allowed origins for local hot reload and WebSocket connections during development.

Diagram sources

Section sources

  • Next.js App Router
    • Internationalization plugin integrated for multi-language support.
  • UI Libraries
    • Framer Motion for animations, next-themes for theme switching, clsx/tailwind-merge for class composition.
  • Purpose
    • Provides reusable navigation, layout, and portal components shared across the platform.

Diagram sources

Section sources

Browser Extension (ui-crx) ​

  • Manifest V3
    • Service worker for background tasks, action popup for quick actions, options page for settings.
    • Content scripts injected on all URLs to interact with pages.
  • Permissions
    • Tabs, downloads, storage, scripting, cookies, context menus, and host permissions for all URLs.
  • Integration
    • Collects data from active tabs and communicates with ui-web via messaging or shared storage.

Diagram sources

Section sources

Dependency Analysis ​

  • Shared UI Library: Arco Design is used across ui-web and ui-web-admin for consistent components.
  • Visualization: ECharts is present in ui-web for charts; ensure consistent theming and responsive sizing.
  • State Management: Zustand is used in ui-web for global state; ensure selectors and slices are optimized.
  • Routing and Rewrites: Both ui-web and ui-web-admin rely on Next.js rewrites to route API traffic to backend services.
  • Internationalization: ui-web-top integrates next-intl for multi-language support.

Diagram sources

Section sources

Performance Considerations ​

  • Next.js App Router
    • Use route groups and dynamic routes to modularize pages and reduce initial bundle size.
    • Enable static generation where appropriate and leverage incremental static regeneration for frequently updated dashboards.
  • ECharts
    • Defer rendering until container is visible; use resize handlers to avoid unnecessary reflows.
    • Minimize chart updates by batching state changes and using efficient data structures.
  • Zustand
    • Keep state flat and granular; split stores by domain to prevent unnecessary re-renders.
    • Use shallow equality checks and avoid deep object updates.
  • Bundling and Transpilation
    • ui-web config transpiles @arco-design/web-react and optimizes imports to reduce bundle size.
    • Tailwind CSS purging and component-level styling help minimize CSS footprint.
  • API Calls
    • Use rewrites to consolidate API endpoints behind a gateway or direct routes; implement caching and pagination.
  • Cross-Browser Compatibility
    • Target ES2017 and ensure polyfills for older browsers if needed; test with supported browsers in production environments.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • API Proxy Issues
    • Verify rewrite rules match backend service endpoints; confirm gateway URL configuration in environment variables.
  • Authentication Flow
    • Ensure auth rewrites are active and tokens are stored securely; check middleware for protected routes.
  • Hot Reload and Dev Origins
    • ui-web-admin allows specific development origins; confirm ports and protocols match allowed entries.
  • Extension Permissions
    • Confirm manifest permissions align with intended functionality; test content script injection and messaging.

Section sources

Conclusion ​

The BI Analysis Platform’s frontend applications are built on Next.js 16 with a consistent architecture across ui-web, ui-web-admin, ui-web-top, and ui-crx. TypeScript and Tailwind CSS ensure maintainability and responsiveness. ECharts and Zustand enable rich visualizations and state management. Environment-driven rewrites streamline API routing, while internationalization and component libraries standardize the user experience. Following the performance and troubleshooting recommendations will help maintain a robust, scalable frontend ecosystem.