# PROJECT KNOWLEDGE BASE

**Generated:** 2026-02-18
**Stack:** React 19, Vite, TypeScript, TanStack (Router, Query, Form), Tailwind CSS, Shadcn/UI

## OVERVIEW
Modern React SPA using Schema-Driven Development (OpenAPI) and file-based routing.
Container-first deployment (Caddy + Podman/Docker).

## STRUCTURE
```
.
├── src/
│   ├── client/       # Generated API client (OpenAPI-TS)
│   ├── components/   # UI & Feature components
│   │   ├── events/   # [COMPLEX] Event system + KYC flow
│   │   └── ui/       # Shadcn/UI base components
│   ├── hooks/        # Custom hooks (Data & UI)
│   ├── routes/       # TanStack Router file-based routing
│   ├── stories/      # Storybook stories (Test source)
│   └── main.tsx      # Entry point (No App.tsx usage)
├── Containerfile     # Multi-stage build (Node -> Caddy)
└── openapi-ts.config.ts # API generation config
```

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| **Routing** | `src/routes/` | File-based. `__root.tsx` is layout. `_workbenchLayout` is main app. |
| **API/Data** | `src/client/` | Generated via `pnpm gen`. DO NOT EDIT manually. |
| **Events/KYC** | `src/components/events/` | Complex container-view + Zustand state machine. |
| **UI Components** | `src/components/ui/` | Shadcn/UI. Extended in `shadcn-io` subdir. |
| **Testing** | `src/stories/` | Stories serve as tests via Vitest + Playwright. |

## CONVENTIONS
- **Style**: Antfu ESLint. 2 spaces. Semicolons. Single quotes.
- **Routing**: TanStack Router. Use `Link` component. File nesting determines URL.
- **State**: Server state = TanStack Query. Local complex state = Zustand. Global UI = Context.
- **Testing**: Create `.stories.tsx` for components. No separate `tests/` folder for units.
- **Imports**: Use `@/` alias for `src/`.

## ANTI-PATTERNS (THIS PROJECT)
- **Manual API Calls**: ALWAYS use generated hooks from `@/client`.
- **Global State**: Avoid Redux/Zustand for server data. Use Query Cache.
- **Dead Code**: `src/App.tsx` is unused. Ignore it.
- **`any` Usage**: Strictly forbidden. Use `unknown` or fix generated types.
- **Nesting**: Do not nest API logic inside `src/client` manually.

## COMMANDS
```bash
pnpm dev          # Start Vite dev server
pnpm build        # TSC + Vite build
pnpm gen          # Regenerate API client (requires internal network)
pnpm storybook    # Start component workbench
pnpm test         # Run Vitest (headless browser)
```

## NOTES
- **Proxy**: API requests proxy to `http://10.8.0.11:8000` (VPN/Internal).
- **Deployment**: Uses Caddy as web server in production container.
- **Auth**: Handled via `useUserInfo` suspense query.