flvx/vite-frontend/AGENTS.md

VITE FRONTEND KNOWLEDGE BASE

Generated: Thu Feb 19 2026 Commit: 137c34e Branch: main Tag: 2.1.4-rc2

OVERVIEW

Web management console for FLVX. Stack: React 18, rolldown-vite, TypeScript, Tailwind CSS v4, shadcn/radix primitives with HeroUI-compatible bridge.

STRUCTURE

vite-frontend/
├── src/
│   ├── api/                      # Axios wrapper + typed endpoint helpers
│   ├── components/ui/            # shadcn/radix primitive components
│   ├── shadcn-bridge/heroui/     # HeroUI-compatible facade used by pages/layouts
│   ├── pages/                    # Route views + page modules (forward/node/tunnel split helpers)
│   ├── hooks/                    # H5/WebView/mobile hooks
│   ├── styles/
│   │   ├── globals.css           # Base styles + imports tailwind-theme.pcss
│   │   └── tailwind-theme.pcss   # Tailwind v4 @theme inline semantic token mapping
│   ├── App.tsx                   # Routes + ProtectedRoute + H5 layout selection
│   ├── main.tsx                  # ReactDOM + BrowserRouter + Provider
│   └── provider.tsx              # Toast/theme/provider composition
├── components.json               # shadcn/ui config
├── tailwind.config.js            # Compatibility config still used by migration scaffolding
├── vite.config.ts                # base '/', host 0.0.0.0:3000; build minify/treeshake disabled
└── package.json

WHERE TO LOOK

Task	Location	Notes
Route definitions	src/App.tsx	React Router v6 + ProtectedRoute
API Client/Auth header	src/api/network.ts	Sends raw JWT in Authorization header
Login Flow	src/pages/index.tsx	Calls login(), stores localStorage.token
Auth helpers	src/utils/auth.ts, src/utils/jwt.ts	Role checks + token expiration parsing
UI bridge usage	src/shadcn-bridge/heroui/	Import from bridge, not @heroui/*
Button parity mapping	src/shadcn-bridge/heroui/button.tsx	Legacy color/variant mapped to shadcn classes
Semantic theme tokens	src/styles/tailwind-theme.pcss	Restores classes like bg-primary, border-input
Theme wiring	src/styles/globals.css	Must import ./tailwind-theme.pcss

CONVENTIONS

• Auth Header: Use raw JWT token (no Bearer prefix).
• API Envelope: Responses follow {code, msg, data, ts}.
• UI Imports: Use src/shadcn-bridge/heroui/* in app pages/layouts for compatibility.
• Semantic Colors: Keep globals.css -> tailwind-theme.pcss import intact or semantic classes break.
• Build profile: minify: false, treeshake: false for easier debugging.
• Layout mode: H5/mobile mode still controlled by existing route/query and hook logic.

ANTI-PATTERNS

• DO NOT ADD Bearer to auth header in frontend requests.
• DO NOT REINTRODUCE @heroui/* or @nextui-org/* dependencies.
• DO NOT REMOVE src/styles/tailwind-theme.pcss import from src/styles/globals.css.
• DO NOT ADD frontend tests; no Vitest/Jest setup exists.

NOTES

• PR #144 (shadcn migration) and PR #142 (user-group binding) are merged in main.
• Release tag 2.1.4-rc2 points to commit 137c34e.
• Button border/color parity depends on both bridge mapping and semantic Tailwind token export.
• Uses rolldown-vite (experimental Rust bundler) instead of standard Vite.

COMMANDS

cd vite-frontend
npm run dev
npm run build
npm run lint