# Repository Guidelines

## Project Structure & Module Organization
The Vite client lives here; runtime code sits under `src`, separated by domain: `src/app` for routing/layout, `src/modules` for feature bundles, `src/providers` for cross-cutting contexts, `src/shared` for reusable UI/logic, `src/api` and `src/stores` for data access and state. Global styles and fonts live in `src/index.css` and `src/assets`. Static files go in `public`. Keep feature-specific assets colocated with their module to ease tree shaking.

## Build, Test, and Development Commands
- `npm install` installs all workspace dependencies; rerun after lockfile updates.
- `npm run dev` starts Vite with fast refresh at http://localhost:5173 for interactive work.
- `npm run build` performs a type-check (`tsc -b`) and production bundle; fail the PR if this fails.
- `npm run lint` applies the shared ESLint config; fix all warnings before review.
- `npm run preview` serves the built `dist` bundle to mirror production.

## Coding Style & Naming Conventions
Use TypeScript with ES modules and React 19. Prefer functional components and hooks; move shared hooks/utilities into `src/shared`. Adopt 2-space indentation, single quotes in TS/TSX, and keep components under 200 lines. Name components in PascalCase (`UserPanel`), hooks in camelCase with a `use` prefix, and files that match their default export (`src/modules/auth/LoginForm.tsx`). Format via Prettier 3.6 before committing.

## Testing Guidelines
Automated tests are not wired yet; add Vitest + React Testing Library as coverage grows. Place specs next to implementation under `__tests__` folders and name them `*.spec.tsx`. Target >80% coverage for new modules and capture edge-case scenarios (loading, error boundaries). Until automation exists, record manual QA steps and verify critical flows via `npm run preview`.

## Commit & Pull Request Guidelines
Use imperative subjects in the form `type(scope): summary`, e.g., `feat(profile): add avatar upload`. Reference issues/Jira IDs in the body and call out breaking changes explicitly. Pull requests should describe intent, list validation commands or screenshots, and link any related backend work. Keep diffs focused (<400 LOC) and ensure `build` and `lint` pass before requesting review.

## Security & Configuration Tips
Do not commit `.env*` files; rely on `.env.example` to document required keys and load values through `import.meta.env`. Treat API endpoints and tokens as secrets managed by the backend. Run `npm audit` monthly and upgrade high-risk dependencies immediately. Avoid embedding credentials or irreversible IDs in client bundles.
