Dashboard Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Dashboard is the primary management interface for Freebuff Proxy. It operates as a Single Page Application (SPA) designed for high performance and zero build-chain overhead. The system allows users to manage proxies, accounts, and API keys entirely through the web console, eliminating the need to edit configuration files manually.
The architecture emphasizes a "no build chain" philosophy, where TypeScript source files are served directly to the browser after undergoing type stripping on the server. This design ensures the dashboard remains lightweight while providing administrative capabilities like system monitoring and real-time logs.
Sources: dashboard/AGENTS.md:6-12, README_EN.md:104-106, README.md:120-122
Core Architectural Principles
Zero Build Chain Implementation
The dashboard consists entirely of .ts source files. The backend server uses Node's stripTypeScriptTypes to remove types before serving these files to the browser. As a result:
- The browser does not use bundlers or transpilers.
- Browser-incompatible syntax (decorators, namespaces, enums) is forbidden.
- Module imports must include full relative paths and
.tsextensions. - Third-party dependencies like React or Vue are prohibited; components use manual DOM manipulation.
Sources: dashboard/AGENTS.md:6-14, AGENTS.md:46-48
Performance and Resource Management
The system enforces strict performance rules to ensure the first screen opens instantly. Large third-party assets, such as the Monaco Editor (3.7MB), use lazy loading and are only fetched when the user specifically accesses the related functionality. Heavy vendors are placed in the vendor/ directory and exempted from linting and type checks to avoid overhead during development.
Sources: dashboard/AGENTS.md:27-32, test/AGENTS.md:38-42
Component Structure and Directory Responsibilities
The dashboard is organized into logical layers, ranging from the core application entry to individual view components and utility libraries.
| Path | Responsibility |
|---|---|
app.ts | Main entry point and source of imports. |
lib/ | Shared utilities: dom.ts (DOM manipulation), api.ts (API requests), ui.ts (Toasts/Progress), state.ts. |
views/shell/ | Core shell including navigation (renderNav) and hash-based routing. |
views/<page>/ | Individual page views (e.g., overview, settings, users). |
locale/dict/ | Internationalization (i18n) dictionaries. |
vendor/ | Third-party assets exempted from gate checks. |
Sources: dashboard/AGENTS.md:16-24
Routing and View Management
Hash-based Single Page Application
The dashboard uses hash-based routing (e.g., #overview, #settings). The render function in the shell manages the transitions between states. When the login state changes (login, logout, or 401 error), the entire #app skeleton is rebuilt. Otherwise, the system only updates the content area, preserving the header and navigation.
Sources: dashboard/views/shell/index.ts:16-43
DOM Caching Mechanism
To prevent data loss and improve responsiveness, the dashboard caches rendered view panels in a viewCache Map. When switching routes, the system changes the hidden attribute of the panels instead of removing them from the DOM. This preserves input values, scroll positions, and the state of complex components like the Monaco Editor.
Sources: dashboard/views/shell/index.ts:70-85, dashboard/views/shell/index.ts:110-120
View Rendering Flow
The following diagram illustrates the route rendering process:
Server-Side Integration
The backend serves the dashboard through static routing and specialized API endpoints.
Static File Serving
The server handles dashboard assets via src/web/static.ts. It maps URLs to the filesystem and performs the necessary type stripping for .ts files to enable browser execution.
Sources: src/web/static.ts, dashboard/AGENTS.md:7-9
Control Plane API Routes
The createWebApi function in src/web/routes/index.ts aggregates all administrative routes. These routes are protected by a session check.
| Endpoint Group | Description |
|---|---|
/api/auth/ | Public authentication routes (login/logout). |
/api/system/ | System-level operations (reconnect, restart, data-status). |
/api/accounts/ | Management of Freebuff account credentials. |
/api/proxy/ | Global proxy pool configuration. |
/api/users/ | User and API key management (Admin only). |
Sources: src/web/routes/index.ts:80-117, test/suites/entries/verify/dashboard/route-panel-visibility.ts:58-68
Quality Assurance and Testing
The dashboard architecture is protected by several automated gates to prevent regressions.
- Frontend Smoke Test: Validates that
dashboard/app.tsand locales can be evaluated in a JS engine without ReferenceErrors or Temporal Dead Zone (TDZ) issues. - Visibility Regression Test: Ensures that only the active route panel is visible and that DOM caching correctly preserves hidden panels.
- i18n Gate: Scans for hard-coded Chinese characters in the source code and ensures dictionary keys are consistent across languages.
- Performance E2E: Measures page loading speeds and ensures large assets like Monaco are not loaded prematurely.
Sources: test/suites/entries/smoke/smoke-frontend.ts:1-12, test/suites/entries/verify/dashboard/route-panel-visibility.ts:15-30, scripts/check-i18n.ts:10-20, test/AGENTS.md:38-42
The dashboard architecture provides a robust, low-overhead management layer for Freebuff Proxy by combining modern Single Page Application techniques with a simplified build-less development flow.