Files

Signed-off-by: Noa Virellia <noa@requiem.garden>

2026-02-18 11:54:42 +08:00

2.7 KiB

Raw Blame History

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

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.

2.7 KiB Raw Blame History