Skip to main content

02 - Frontend Architecture Design

This document details the technical stack, core dependencies, module organization, and design system of the Taimoe Enterprise AI Gateway frontend management console (taimoe-console).

1. Technology Stack​

The frontend avoids traditional Next.js SSR complexity, opting for a lightweight, fast, and stable modern SPA (Single Page Application) architecture:

  • Build Tool: Vite (8.x). Provides sub-second Hot Module Replacement (HMR) and optimized production bundling performance.
  • Core Framework: React 19. Leverages modern React 19 rendering features to ensure maximum performance and clean codebase architecture.
  • Component Library: Material UI (MUI 9.0.0+). Paired with @emotion/react and @emotion/styled to deliver a consistent, professional, high-contrast enterprise admin UI.
  • Routing: React Router Dom (7.x). Client-side route management enabling smooth, seamless page transitions without page reloads.
  • Authentication: @react-oauth/google. Deeply integrated with Google Identity Services to provide secure Single Sign-On (SSO / Google OAuth) and identity token propagation.
  • API Client: Axios. Powerful Request/Response Interceptors to attach API tokens before requests, handle automatic 401 logouts, and manage global error handling.
  • Metrics & Charts: echarts-for-react (ECharts 6.x). High-performance charting library connected directly to ClickHouse metric endpoints to render interactive QPS trends, latency distribution (P50/P95), and cost breakdown pie charts.

2. Monorepo & UI Workspace​

Frontend codebase is organized under /frontend/, leveraging pnpm workspaces for cross-project dependency management:

  • @taimoe/ui: Located at packages/ui, containing shared UI components, custom base styling, color tokens, shared typography, and button components.
  • taimoe-console: The primary Vite + React admin console project.
  • taimoe-website: The public-facing marketing and documentation portal built with Astro.
flowchart TD
    subgraph Browser["User Browser"]
        Console["taimoe-console (React 19 SPA)"]
        Router["React Router 7"]
        State["Client State & Auth Token"]
    end

    subgraph DesignSystem["UI & Components"]
        MUI["Material UI Components"]
        ECharts["ECharts 6 (Metrics & Analytics)"]
        SharedUI["@taimoe/ui Shared Library"]
    end

    subgraph ClientLayer["API Client & Interceptors"]
        Axios["Axios Client"]
        AuthInterceptor["Bearer Token & Auth Interceptor"]
        ErrInterceptor["Global Error & 401 Handler"]
    end

    Console --> Router
    Console --> State
    Console --> MUI
    Console --> ECharts
    MUI --> SharedUI

    Console --> Axios
    Axios --> AuthInterceptor
    Axios --> ErrInterceptor
    AuthInterceptor -->|Secure REST Requests| Backend["FastAPI Control Plane"]

3. UI/UX Design System​

To maintain a financial-grade, clean, and high-contrast admin console, frontend development strictly follows these guidelines:

  • Monochromatic Iconography:
    • Icons strictly use monochromatic palette (@mui/icons-material), matching text contrast and avoiding unnecessary visual distraction.
    • Colors are reserved exclusively for status indicators (e.g., green for healthy, red for blocked, orange for rate-limited).
    • Avoid wrapping icons in colored circular/square background badges to maintain a flat and transparent feel.
  • Typography-Driven Hierarchy:
    • Use font size, weight (font-weight: 500/700), and grayscale variants (text-secondary) to build visual hierarchy.
    • Avoid heavy card containers with thick borders. Use whitespace spacing and subtle dividers (<Divider /> / <hr />) for clean sectioning.
  • Interactive Drawer Controls:
    • When an administrator clicks a Virtual Key, Policy, or Audit Log entry in the Console, a right-side Drawer panel opens to display detailed configurations, event history, and support inline editing.

4. Key Workflows​

The console focuses on Key Provisioning, Policy Application, and Platform Observability:

  1. Virtual Key Management: Admins can generate new Virtual Keys for specific projects, trigger key rotation, or instantly revoke compromised keys.
  2. Policy Configuration: Visual forms to configure project-level rate limits (RPM, RPD), cost guards, and PII masking policies.
  3. Audit Log Viewer: Multi-dimensional filters (time range, project, status codes) with expandable drawer views that pull full Request/Response JSON Payloads from Object Storage for security audits.
  4. Observability Dashboard: Real-time rendering of gateway performance metrics and cost allocation using ECharts.