62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 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.
|