Application Structure and Dependencies

Relevant source files

• .github/workflows/build.yml
• .github/workflows/weblate-pull.yml
• .github/workflows/weblate-sync.yml
• app/components.d.ts
• app/package.json
• app/src/version.json
• app/vite.config.ts
• docs/package.json
• go.mod
• go.sum
• router/routers.go

This document describes the frontend application structure, project organization, dependency management, and build configuration for Nginx UI. It covers the Vue.js application located in the app/ directory, including its package structure, core dependencies, development tooling, and configuration files.

For backend dependencies and Go module structure, see Backend Architecture. For build and deployment pipeline details, see Frontend Build Process and Multi-Platform Compilation.

---

Project Overview

The frontend application is a Vue 3 single-page application built with Vite and TypeScript. The project is named nginx-ui-app-next and uses pnpm as its package manager. The application follows modern Vue.js best practices with composition API, TypeScript support, and modular component architecture.

Key Characteristics:

• Module type: ES Module ("type": "module")
• Package manager: pnpm 10.18.3 (locked via packageManager field)
• Current version: 2.2.0
• Build output: Static assets distributed as compressed archive

Sources: app/package.json1-95

---

Directory Structure

Component Organization by Feature Domain:

Domain	Components	Purpose
Nginx Configuration	NgxConfigEditor, NginxControl, InspectConfig	Block-based config editing and Nginx process control
Certificate Management	AutoCertForm, CertInfo	ACME configuration and certificate display
Multi-Node Clustering	NodeCard, NodeSelector, NamespaceTabs, SyncNodesPreview	Node management and namespace organization
Analytics & Monitoring	Chart/*, AreaChart, RadialBarChart	Real-time metrics visualization
Configuration Management	ConfigHistory, CodeEditor, BaseEditor	Config versioning and editing
Authentication	TwoFA, OTPInput	2FA/TOTP and passkey authentication
System Management	SelfCheck, SystemRestore, Notification	Health checks and backup/restore
LLM Integration	LLM/*, ChatMessage, ChatMessageInput	AI-assisted configuration

Sources: app/components.d.ts1-143

---

Core Dependencies

Vue Ecosystem

Package Versions and Purposes:

Package	Version	Purpose
vue	3.5.22	Core Vue 3 framework with Composition API
vue-router	4.6.3	Official routing library for SPA navigation
@vue/reactivity	3.5.22	Standalone reactivity system
@vue/shared	3.5.22	Shared utilities across Vue packages
@vueuse/core	13.9.0	Collection of essential composition utilities
@vueuse/components	13.9.0	Renderless component utilities
@vueuse/integrations	13.9.0	Integration wrappers for third-party libraries
@vueuse/router	13.9.0	Router-specific composition utilities

Sources: app/package.json15-62

---

UI Framework and Components

Component Library Details:

Package	Version	Use Case
ant-design-vue	4.2.6	Primary UI component library (tables, forms, modals, etc.)
@ant-design/icons-vue	7.0.1	Icon components for Ant Design
echarts	6.0.0	Real-time analytics charts (CPU, memory, network)
apexcharts	5.3.5	Additional chart types and visualizations
vue3-ace-editor	2.2.4	Nginx configuration code editor with syntax highlighting
@xterm/xterm	5.5.0	Terminal emulator for remote shell access
@simplewebauthn/browser	13.2.2	WebAuthn/FIDO2 passkey authentication
vue3-otp-input	0.5.40	One-time password input for 2FA/TOTP
splitpanes	4.0.4	Resizable split views in configuration editor
vuedraggable	4.1.0	Drag-and-drop for upstream server ordering

Sources: app/package.json15-62

---

State Management and Internationalization

State Management:

• Pinia 3.0.3: Official Vue state management replacing Vuex
• Persistence Plugin: Automatically saves store state to localStorage
• Store organization follows feature-based structure (see State Management with Pinia)

Internationalization:

• vue3-gettext: GNU gettext-based translation system
• 14 supported languages with .po files in src/language/
• Country name localization: i18n-iso-countries for dropdown menus
• Translation workflow: Extract → Weblate → Compile → Bundle (see Internationalization System)

Sources: app/package.json44-45 app/package.json60 app/package.json38

---

HTTP Client and Utilities

HTTP and Real-Time Communication:

Package	Version	Purpose
axios	1.12.2	REST API client with request/response interceptors
reconnecting-websocket	4.4.0	WebSocket with automatic reconnection for real-time updates
sse.js	2.7.2	Server-Sent Events for streaming updates

Data Processing:

Package	Version	Purpose
dayjs	1.11.18	Date/time formatting and manipulation
lodash	4.17.21	Utility functions (debounce, throttle, deep clone, etc.)
uuid	13.0.0	UUID generation for client-side IDs
marked	16.4.0	Markdown to HTML conversion for documentation

Security:

Package	Version	Purpose
jsencrypt	3.5.4	RSA public key encryption for sensitive data
@fingerprintjs/fingerprintjs	4.6.2	Browser fingerprinting for device tracking
universal-cookie	8.0.1	Cross-platform cookie management

Sources: app/package.json34-62

---

CURD Framework Integration

The frontend uses a custom CRUD framework for rapid API integration:

The @uozi-admin/curd package provides:

• Type-safe API client generation
• Automatic CRUD form generation
• List views with pagination, sorting, filtering
• Optimistic UI updates
• Error handling and retry logic

Translation strings for CRUD operations are auto-generated via:

Sources: app/package.json21-22 app/package.json13

---

Build Tooling and Vite Configuration

Vite Configuration Overview

Key Configuration Details

Path Resolution app/vite.config.ts20-34:

• @/ alias resolves to src/ directory
• Supports extensions: .mjs, .js, .ts, .jsx, .tsx, .json, .vue, .less

Auto-Import Configuration app/vite.config.ts45-75:

• Auto-imports Vue APIs (ref, computed, watch, etc.)
• Auto-imports router functions (useRouter, useRoute)
• Auto-imports Pinia stores
• Custom imports: $gettext, T, useGlobalApp
• Generates .eslint-auto-import.mjs for linting

Component Auto-Registration app/vite.config.ts41-44:

• Ant Design Vue components auto-imported on demand
• Custom components auto-registered by directory
• Generates components.d.ts type declarations

CSS Configuration app/vite.config.ts79-88:

• Less preprocessor with customized Ant Design theme variables
• JavaScript-enabled Less for dynamic theming

Development Server app/vite.config.ts89-98:

• Default port: 3002 (configurable via VITE_PORT)
• Proxies /api/* requests to backend (default: localhost:9001)

Sources: app/vite.config.ts1-104 app/package.json64-93

---

Development Dependencies and Tooling

TypeScript and Linting

NPM Scripts app/package.json6-13:

Script	Command	Purpose
dev	vite --host	Start development server with network access
typecheck	vue-tsc --noEmit	Type-check without emitting files
lint	eslint .	Check code style and errors
lint:fix	eslint --fix .	Auto-fix linting issues
build	vite build	Production build
preview	vite preview	Preview production build
gettext:extract	generate-curd-translations && vue-gettext-extract	Extract translatable strings

Type Checking:

• vue-tsc performs full TypeScript type checking including .vue files
• Extends base Vue TypeScript configuration from @vue/tsconfig
• Run automatically in CI via .github/workflows/build.yml

Code Quality:

• @antfu/eslint-config: Opinionated ESLint preset by Anthony Fu
• eslint-plugin-sonarjs: Detects bugs and code smells
• Auto-fix on save in most IDEs

Sources: app/package.json64-93

---

Icon System

Icon Packages:

• @iconify/vue: Universal icon framework with 200,000+ icons
• @iconify-json/fa: Font Awesome icon set
• @iconify-json/tabler: Tabler icon set (primary icons)
• vite-svg-loader: Import SVG files as Vue components

Usage Example:

Sources: app/package.json66-71

---

Configuration Files

Build Configuration Files

Configuration File Purposes:

File	Purpose	Generated
vite.config.ts	Vite build configuration, plugins, proxy settings	No
package.json	Dependencies, scripts, package metadata	No
tsconfig.json	TypeScript compiler options	No
.env.production	Production environment variables	No
.env.development	Development environment variables	No
components.d.ts	Auto-generated component type declarations	Yes
auto-imports.d.ts	Auto-generated API import types	Yes
.eslint-auto-import.mjs	ESLint globals for auto-imports	Yes
version.json	Build version and ID tracking	Yes

Environment Variables app/vite.config.ts90-97:

• VITE_PORT: Development server port (default: 3002)
• VITE_PROXY_TARGET: Backend API proxy target (default: http://localhost:9001)
• Environment files loaded by Vite in order: .env.local → .env.[mode] → .env

Version Tracking app/src/version.json1:

• build_id: Increments per build for cache busting
• total_build: Total number of builds since project inception
• Generated during frontend build process

Sources: app/vite.config.ts1-104 app/src/version.json1 app/package.json1-95

---

Build and Distribution Pipeline

Frontend Build Process

Build Process Details .github/workflows/build.yml43-97:

1. Environment Setup (macOS-latest)

   • Node.js: Latest current version
   • Package manager: pnpm (via corepack)
   • Dependencies installed from lockfile

2. Quality Checks

   • pnpm lint: ESLint validation
   • pnpm typecheck: TypeScript type checking
   • Fails build if errors detected

3. Build Execution

   • npx update-browserslist-db@latest: Update browser support data
   • pnpm build: Vite production build
   • Output: app/dist/ directory

4. Compression

   • Create tar archive: tar -C app -cf - dist
   • XZ compression (level 9): Typically 75-85% size reduction
   • Final artifact: app/dist.tar.xz

5. Distribution

   • Upload to GitHub Actions artifacts (available to backend build)
   • Backend downloads and extracts during build
   • Embedded into Go binary via go:embed directive

Compression Statistics .github/workflows/build.yml78-89: The build workflow calculates and displays compression savings, typically showing 75-85% reduction in file size.

Sources: .github/workflows/build.yml43-109

---

Internationalization Build Integration

Translation Build Process:

1. String Extraction app/package.json13:

   • Generates CRUD translations: src/language/curd.ts
   • Extracts strings from Vue templates: vue-gettext-extract

2. Weblate Synchronization .github/workflows/weblate-sync.yml1-87:

   • Daily automated sync (18:15 UTC)
   • Pulls translations from Weblate
   • Merges to dev branch
   • Pushes updates back to Weblate

3. Weblate Pull on Release .github/workflows/weblate-pull.yml1-33:

   • Resets Weblate repository on PR merge or release
   • Ensures translations are up-to-date

4. Build-Time Compilation:

   • vue3-gettext compiles .po files during Vite build
   • Translations bundled into JavaScript chunks
   • Runtime language switching without reloading

Supported Languages: 14 languages including English, Chinese (Simplified/Traditional), Spanish, French, German, Japanese, etc. (see Supported Languages)

Sources: .github/workflows/weblate-sync.yml1-87 .github/workflows/weblate-pull.yml1-33 app/package.json13

---

Summary

The frontend application structure demonstrates a modern Vue 3 architecture with:

• Modular Organization: Feature-based component structure with clear domain separation
• Type Safety: Full TypeScript support with auto-generated type declarations
• Developer Experience: Auto-import APIs/components, hot reload, and comprehensive tooling
• Performance: Tree-shaking, code splitting, lazy loading, and compression
• Internationalization: 14-language support with automated translation workflows
• Build Pipeline: Single-build frontend distribution embedded in multi-platform backend binaries

Key dependency categories:

1. Vue Ecosystem: Vue 3.5, Router 4.6, VueUse utilities
2. UI Framework: Ant Design Vue 4.2 with custom theming
3. State Management: Pinia 3.0 with persistence
4. Internationalization: vue3-gettext with Weblate integration
5. Build Tooling: Vite 7.1 with comprehensive plugin ecosystem
6. Data Visualization: ECharts and ApexCharts
7. Code Editing: Ace Editor with Nginx syntax support
8. Authentication: WebAuthn/Passkeys and 2FA/TOTP support

The build process produces a compressed 75-85% size-reduced artifact that is embedded into the Go backend binary, enabling single-binary distribution across 14 platform/architecture combinations.