# AI Agent Instructions: Fullstack Vite 7 (React) + Express + TypeScript + npm

You are an expert AI fullstack software engineer specialized in Vite 7, React, Express, TypeScript, and modern web architectures. Follow these rules strictly when modifying this codebase.

## 1. Project Structure & Context
* **Frontend:** React SPA powered by Vite 7.x (Entry: `src/main.tsx` or client folder).
* **Backend:** Express Node.js application (Server entry: `server.ts` or server folder).
* **Package Manager:** npm (`package-lock.json` is the strict source of truth).
* **TypeScript Setup:** Strict Mode enabled independently across both environments.

## 2. Express Backend TypeScript Rules
* **Typed Request/Response:** Explicitly type Express route handlers using native Express types:
  ```typescript
  import { Request, Response, NextFunction } from 'express';
  // Example for typed request bodies/params:
  interface CreateUserBody { username: string; }
  app.post('/user', (req: Request<{}, {}, CreateUserBody>, res: Response) => { ... });
  ```
* **Async Error Catching:** Always wrap async middleware/route handlers in `try/catch` and pass errors to `next(err)`. Do not let unhandled promise rejections crash the Node process.
* **Shared Types:** If frontend and backend share types (e.g., API payloads, User models), place them in a shared directory or export them cleanly from the backend to prevent duplicating code.

## 3. Frontend React + Vite Rules
* **Component Typings:** Use standard type inference or explicit return types (`function Component(): React.JSX.Element`). Avoid the legacy `React.FC`.
* **Strict Prop Types:** Every component must have an explicitly typed `interface` or `type` for its props. No implicit `any`.
* **Event Handlers:** Use exact React synthetic event types (e.g., `React.ChangeEvent<HTMLInputElement>`) instead of generic native events.
* **File Extensions:** Use `.tsx` exclusively for files containing JSX. Use `.ts` strictly for pure logic, hooks, or type definitions.

## 4. Strict Code Quality & Native Guards
* **No `any`:** Never use `any`. Use `unknown` for unpredictable runtime data (like Express `req.body` or frontend `fetch` payloads).
* **No Validation Libraries:** Do not install Zod, TypeBox, or Yup. Write explicit, manual type predicate functions (`function isUser(obj: any): obj is User`) to safely validate runtime data incoming to both the server and client.
* **No Enums:** Avoid TypeScript `enum`. Use string-literal unions (`type Status = 'active' | 'pending'`) or `const StatusEnum = { ... } as const`.

## 5. Verification & Workflow Commands
Before declaring a task complete, you must verify both environments compile flawlessly via npm:
* **Install Dependencies:** `npm install`
* **Type-Check Project:** Run the designated workspace or folder type-checking scripts (e.g., `npm run type-check` or `npx tsc --noEmit` across both roots).
* **Build Verification:** Run production build scripts (e.g., `npm run build`) to ensure both Express asset compilation and Vite bundling pass without error.

## 6. How to Respond
* **Verify Types First:** Run type-checking commands automatically after modifying files to capture compilation breaks before presenting the solution.
* **Targeted Diffs:** Provide concise, targeted updates. Do not rewrite whole files if only a few lines change.
* **Self-Correct:** If a build command fails, read the compiler/Vite/Node logs, fix the root cause, and re-test before asking the user for help.