Navigation Components (ui-web-top)

**Referenced Files in This Document** - [[package.json]](file/ui-web-top/package.json) - [[next.config.ts]](file/ui-web-top/next.config.ts) - [[tsconfig.json]](file/ui-web-top/tsconfig.json) - [[middleware.ts]](file/ui-web-top/src/middleware.ts) - [[routing.ts]](file/ui-web-top/src/i18n/routing.ts) - [[request.ts]](file/ui-web-top/src/i18n/request.ts) - [[layout.tsx]](file/ui-web-top/src/app/locale/layout.tsx) - [[layout.tsx]](file/ui-web-top/src/app/layout.tsx) - [[Navbar.tsx]](file/ui-web-top/src/components/navbar.tsx) - [[Footer.tsx]](file/ui-web-top/src/components/footer.tsx) - [[ThemeProvider.tsx]](file/ui-web-top/src/components/themeprovider.tsx) - [[LanguageSwitcher.tsx]](file/ui-web-top/src/components/languageswitcher.tsx) - [[ThemeToggle.tsx]](file/ui-web-top/src/components/themetoggle.tsx) - [[env.ts]](file/ui-web-top/src/config/env.ts)

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 Navigation Components (ui-web-top) application that provides portal and navigation functionality across the BI platform. Built with Next.js 16 App Router, the application implements internationalization with next-intl, a responsive design system, and a cohesive component composition pattern. It includes a portal-style layout system, branding components, navigation hierarchy, middleware-based route protection and localization, and integration points with other frontend applications via environment-aware configuration.

Project Structure

The ui-web-top application follows Next.js 16 conventions with the App Router. Key areas:

• Internationalization configuration under src/i18n
• Middleware for routing and locale handling under src/middleware.ts
• Application layouts under src/app/[locale] and src/app/layout.tsx
• Reusable UI components under src/components
• Environment-specific configuration under src/config/env.ts
• Build-time configuration under next.config.ts and tsconfig.json

Diagram sources

• [layout.tsx]
• [layout.tsx]
• [middleware.ts]
• [routing.ts]
• [request.ts]
• [Navbar.tsx]
• [Footer.tsx]
• [ThemeProvider.tsx]
• [LanguageSwitcher.tsx]
• [ThemeToggle.tsx]
• [env.ts]
• [package.json]
• [next.config.ts]
• [tsconfig.json]

Section sources

• [layout.tsx]
• [layout.tsx]
• [middleware.ts]
• [routing.ts]
• [request.ts]
• [Navbar.tsx]
• [Footer.tsx]
• [ThemeProvider.tsx]
• [LanguageSwitcher.tsx]
• [ThemeToggle.tsx]
• [env.ts]
• [package.json]
• [next.config.ts]
• [tsconfig.json]

Core Components

• Navigation Bar (Navbar): Provides desktop and mobile navigation, branding, theme toggle, language switcher, and external links to the console.
• Footer: Displays branding, group links, and legal information with localized content.
• Theme Provider: Manages light/dark/system themes and synchronizes Arco Design theme attributes.
• Language Switcher: Allows switching locales while preserving current route.
• Theme Toggle: Switches between light and dark modes.
• Environment Config: Centralized configuration for URLs across environments (local, dev, test, prod).

Key integration points:

• Uses next-intl for translations and routing-aware navigation.
• Leverages Arco Design components for UI primitives.
• Implements responsive drawer for mobile navigation.

Section sources

• [Navbar.tsx]
• [Footer.tsx]
• [ThemeProvider.tsx]
• [LanguageSwitcher.tsx]
• [ThemeToggle.tsx]
• [env.ts]

Architecture Overview

The application uses Next.js 16 App Router with middleware-driven internationalization. The middleware enforces locale-aware routing and redirects, while the locale layout provides messages and theme providers to all pages. Components consume translations via next-intl hooks and integrate with environment configuration for cross-application links.

Diagram sources

• [middleware.ts]
• [routing.ts]
• [request.ts]
• [layout.tsx]
• [Navbar.tsx]
• [env.ts]

Detailed Component Analysis

Navigation Bar (Navbar)

Responsibilities:

• Renders branding with logo and name from translation namespace Brand.
• Builds navigation items from translation namespace Nav.
• Supports desktop and mobile views with a drawer.
• Integrates ThemeToggle and LanguageSwitcher.
• Opens console URL from environment configuration.

Implementation highlights:

• Uses next-intl hooks for translations and routing-aware Link.
• Uses Arco Design Button and Drawer for UI.
• Mobile drawer toggles visibility and reflects current pathname for active state.
• Opens external console link via environment configuration.

Diagram sources

• [Navbar.tsx]
• [env.ts]

Section sources

• [Navbar.tsx]
• [env.ts]

Footer

Responsibilities:

• Displays branding and slogan.
• Provides external links to group and related sites.
• Shows legal and copyright information in localized text.

Implementation highlights:

• Uses next-intl translations from namespaces Brand and Footer.
• Links are static external links except for the logo link.

Section sources

• [Footer.tsx]

Theme Provider and Theme Toggle

Responsibilities:

• Manage theme state (light, dark, system) with persistence.
• Synchronize Arco Design theme attribute on body element.
• Provide theme toggle button with sun/moon icons.

Implementation highlights:

• ThemeSync effect updates DOM attribute based on resolved theme.
• ThemeToggle handles hydration-safe rendering and theme switching.

Diagram sources

• [ThemeProvider.tsx]
• [ThemeToggle.tsx]

Section sources

• [ThemeProvider.tsx]
• [ThemeToggle.tsx]

Language Switcher

Responsibilities:

• Switch locale without losing current route.
• Provide dropdown with locale options.

Implementation highlights:

• Uses useLocale, useRouter, and usePathname from routing module.
• Calls router.replace with locale to preserve pathname.

Section sources

• [LanguageSwitcher.tsx]

Environment Configuration

Responsibilities:

• Provide environment-aware URLs for official site, console, API gateway, and admin.
• Support multiple deployment environments via environment variables.

Implementation highlights:

• Resolves environment priority from NEXT_PUBLIC_APP_ENV to NODE_ENV.
• Exports shared config object for use across components.

Section sources

• [env.ts]

Internationalization Workflow

The application uses next-intl for routing, server-side message loading, and client-side translation consumption.

Diagram sources

• [middleware.ts]
• [routing.ts]
• [request.ts]

Section sources

• [middleware.ts]
• [routing.ts]
• [request.ts]

Middleware Implementation

Responsibilities:

• Enforce locale-aware routing.
• Protect routes by matching internationalized pathnames and excluding static assets.

Implementation highlights:

• Uses next-intl/middleware with routing configuration.
• Matcher ensures only localized routes and non-static paths are processed.

Section sources

• [middleware.ts]

Portal Layout System

Responsibilities:

• Provide global metadata and theme wrapper.
• Ensure locale validation and message injection.
• Apply Tailwind and Arco Design styles.

Implementation highlights:

• Root layout returns children for App Router.
• Locale layout validates locale, loads messages, and wraps children with NextIntlClientProvider and ThemeProvider.

Section sources

• [layout.tsx]
• [layout.tsx]

Dependency Analysis

External libraries and integrations:

• next-intl: Routing, navigation helpers, server-side message loading, and middleware.
• next-themes: Theme management with system preference support.
• @arco-design/web-react: UI components (Button, Drawer, Dropdown).
• framer-motion and remotion: Animation and video player capabilities.
• tailwind-merge and clsx: Utility-first CSS class composition.

Diagram sources

• [package.json]
• [middleware.ts]
• [routing.ts]
• [request.ts]
• [layout.tsx]
• [Navbar.tsx]
• [LanguageSwitcher.tsx]
• [ThemeToggle.tsx]

Section sources

• [package.json]
• [middleware.ts]
• [routing.ts]
• [request.ts]
• [layout.tsx]
• [Navbar.tsx]
• [LanguageSwitcher.tsx]
• [ThemeToggle.tsx]

Performance Considerations

• Keep translations scoped to namespaces to minimize bundle size.
• Lazy-load animations and videos to reduce initial payload.
• Use next/image for optimized image delivery and avoid unnecessary re-renders by keeping translation keys stable.
• Prefer CSS utilities over heavy component libraries for simple UI elements.

Troubleshooting Guide

Common issues and resolutions:

• Invalid locale causing 404: Ensure routing.locales includes the requested locale and locale layout validates against routing.locales.
• Translations not loading: Verify messages files exist and request.ts imports the correct locale JSON.
• Theme not applying to Arco components: Confirm ThemeProvider wraps the application and ThemeSync sets the arco-theme attribute.
• Language switch not persisting: Ensure router.replace is called with the current pathname and new locale.

Section sources

• [layout.tsx]
• [request.ts]
• [ThemeProvider.tsx]
• [LanguageSwitcher.tsx]

Conclusion

The ui-web-top application demonstrates a clean, modular approach to building navigation and branding components within Next.js 16’s App Router. Its internationalization pipeline, middleware-driven routing, and environment-aware configuration enable seamless integration across the BI platform. The component composition pattern promotes reusability and maintainability, while the responsive design system ensures accessibility across devices.

Appendices

Internationalization Setup

• Define supported locales and default locale in routing configuration.
• Provide server-side message loading per request.
• Consume translations in components via next-intl hooks.
• Use routing-aware Link for locale-preserving navigation.

Section sources

• [routing.ts]
• [request.ts]
• [Navbar.tsx]

Navigation Customization Examples

• Add new menu items: Extend menuItems array with translation keys and route keys.
• Customize branding: Update Brand namespace translations and logo assets.
• Modify theme behavior: Adjust ThemeProvider defaults and ThemeSync logic.

Section sources

• [Navbar.tsx]
• [env.ts]

Responsive Design and Styling

• Tailwind utilities applied for responsive breakpoints and spacing.
• Arco Design components provide consistent UI primitives.
• Theme provider manages color modes and system preference.

Section sources

• [Navbar.tsx]
• [layout.tsx]