# VITE FRONTEND KNOWLEDGE BASE

**Generated:** Thu Feb 26 2026
**Commit:** 21008cc
**Branch:** main
**Tag:** 2.1.5-rc15

## 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 (23 components)
│   ├── pages/                    # Route views + page modules (forward/node/tunnel)
│   ├── 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 for migration scaffolding
├── vite.config.ts                # base '/', host 0.0.0.0:3000; 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 debugging.
- **Layout mode**: H5/mobile mode 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
- Uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite.
- Build outputs are non-minified (debugging mode).
- No test infrastructure exists (Vitest/Jest not configured).

## COMMANDS
```bash
cd vite-frontend
npm run dev
npm run build
npm run lint
```