vitepress-template

Appearance

Admin Panel (ui-web-admin) ​

**Referenced Files in This Document** - [[package.json]](file/ui-web-admin/package.json) - [[next.config.ts]](file/ui-web-admin/next.config.ts) - [[src/config/env.ts]](file/ui-web-admin/src/config/env.ts) - [[src/app/layout.tsx]](file/ui-web-admin/src/app/layout.tsx) - [[src/app/login/page.tsx]](file/ui-web-admin/src/app/login/page.tsx) - [[src/app/(dashboard)/layout.tsx]](file/ui-web-admin/src/app/dashboard)/layout.tsx) - [[src/app/(dashboard)/dashboard/page.tsx]](file/ui-web-admin/src/app/dashboard)/dashboard/page.tsx) - [[src/app/(dashboard)/system/users/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/users/page.tsx) - [[src/app/(dashboard)/cms/news/page.tsx]](file/ui-web-admin/src/app/dashboard)/cms/news/page.tsx) - [[src/lib/request.ts]](file/ui-web-admin/src/lib/request.ts) - [[src/lib/api.ts]](file/ui-web-admin/src/lib/api.ts) - [[src/lib/plasmic.ts]](file/ui-web-admin/src/lib/plasmic.ts) - [[src/components/ArcoCompat.tsx]](file/ui-web-admin/src/components/arcocompat.tsx)

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
  10. Appendices

Introduction ​

This document describes the Admin Panel (ui-web-admin), a system administration interface built with Next.js 16 App Router. It covers the application’s architecture, component hierarchy, routing patterns, and administrative capabilities including user administration, tenant management, role-based access control, system configuration, and CMS content management. It also documents API integration patterns, authentication and authorization flows, security considerations, responsive design and accessibility, and practical workflows for common administrative tasks.

Project Structure ​

The Admin Panel follows Next.js 16 conventions with App Router. Key areas:

  • Application shell and global styles under src/app
  • Feature pages grouped by functional domain (dashboard, system, tenants, cms)
  • Shared libraries for API, request handling, and CMS integration
  • Environment-aware configuration and routing rewrites

Diagram sources

Section sources

Core Components ​

  • Authentication and session management via local storage and Bearer tokens
  • Centralized request layer with unified error handling and 401 redirection
  • Feature-specific API modules for system management, tenant management, and CMS
  • Theme persistence and Arco Design integration
  • Environment-driven routing rewrites to backend services or gateway

Key implementation references:

Section sources

Architecture Overview ​

The Admin Panel uses a layered architecture:

  • Presentation layer: Next.js App Router pages and shared components
  • Domain services: Feature-specific API modules (users, tenants, system, CMS)
  • Infrastructure: Unified request layer with environment-aware routing
  • Security: JWT-based Bearer tokens stored in browser local storage

Diagram sources

Detailed Component Analysis ​

Authentication and Authorization Flow ​

  • Login page posts credentials to the auth service and stores the Bearer token in local storage
  • Dashboard layout fetches user info on mount and guards routes by checking token presence
  • Request layer automatically attaches Authorization header and handles 401 by clearing token and redirecting to login
  • Logout triggers backend logout and clears token

Diagram sources

Section sources

System Management: User Administration ​

  • Lists users with pagination and filters
  • CRUD operations with modal forms
  • Password reset and status toggling
  • Integrates with departments and roles for assignment

Diagram sources

Section sources

System Monitoring and Dashboard ​

  • Loads summary statistics from tenant-m service via dashboardApi
  • Renders KPI cards and customer status distribution
  • Gracefully handles missing endpoints with fallback values

Diagram sources

Section sources

CMS Management: News ​

  • Integrates with Plasmic CMS via bi-sys configuration keys
  • Queries, creates, updates, and deletes news entries
  • Supports localized content and translation status tagging
  • Uses an API Route proxy to avoid CORS and enforce auth

Diagram sources

Section sources

Routing Patterns and Navigation ​

  • App Router groups: (dashboard) for authenticated area
  • Sidebar navigation drives programmatic routing
  • Environment-aware rewrites route API traffic to gateway or backend services

Diagram sources

Section sources

Dependency Analysis ​

  • Next.js 16 runtime and App Router
  • Arco Design for UI components and theming
  • Plasmic loader for CMS integration
  • Environment-driven configuration and rewrites

Diagram sources

Section sources

Performance Considerations ​

  • Environment-aware rewrites reduce latency by routing through a gateway when configured
  • Pagination on user listings prevents large payloads
  • Local caching of theme preference avoids unnecessary DOM manipulation
  • JSONBig parsing supports large numeric IDs consistently

Recommendations:

  • Enable output: standalone for containerized deployments
  • Consider enabling SWC transpilation for faster builds
  • Monitor API latency per environment and adjust gateway routing accordingly

Section sources

Troubleshooting Guide ​

Common issues and resolutions:

Section sources

Conclusion ​

The Admin Panel leverages Next.js 16 App Router to deliver a secure, modular, and maintainable administration interface. Its layered design separates concerns across presentation, domain services, and infrastructure, while environment-aware routing and centralized request handling simplify integration with backend services and gateways. The system provides robust administrative capabilities for user management, tenant operations, system configuration, and CMS content management, with strong security and UX foundations.

Appendices ​

Administrative Tasks and Workflows ​

Security Considerations ​

  • Tokens stored in browser local storage; ensure HTTPS and secure cookies on backend
  • 401 handling automatically logs out unauthorized sessions
  • API Route proxy for CMS prevents direct browser-to-CMS CORS issues
  • References: [src/lib/request.ts], [src/lib/plasmic.ts]

Accessibility and Responsive Design ​