Imported from XinHu98/seed_sys (AGENTS.md). Install upstream with npx skills add XinHu98/seed_sys. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• server/: Express + Prisma API in TypeScript (src/ routes/services/middleware), compiled to dist/; env config lives in .env with sample .env.example; file uploads land in uploads/.
• client/: Vite + React admin UI (components/, pages/, services/, contexts/, types/, utils/); entry at App.tsx and index.tsx.
• customer/: Vite + React customer portal (Tailwind) with a similar layout.
• shared/: Cross-app TypeScript types; import via @shared/*.
• docs/: Product, design, and audit references; update when flows change.

Build, Test, and Development Commands

• npm run install:all installs root/client/server deps; run once after cloning.
• npm run dev runs API and admin UI together (dev:server + dev:client).
• npm run dev --prefix customer runs the portal locally.
• npm run build builds client and server; npm run start serves compiled API (server/dist/index.js).
• Prisma: npm run db:generate|db:migrate|db:push|db:seed|db:studio --prefix server for schema updates, migrations, seeding, and the studio UI.
• Health check: curl http://localhost:3001/api/health after the server starts.

Coding Style & Naming Conventions

• TypeScript/ESM everywhere; server tsconfig is strict. Prefer 2-space indent, trailing semicolons, and readable arrow functions.
• PascalCase React components and type aliases; camelCase variables/functions; SCREAMING_SNAKE_CASE env keys.
• Keep React logic in components/ and page wiring in pages/; reuse types from shared/types.ts.
• Server routes live in server/src/routes/; keep auth/validation middleware in middleware/; favor explicit input validation before DB calls.

Testing Guidelines

• No formal test suite yet; at minimum run npm run build --prefix server and npm run build --prefix client to catch type errors.
• For new features, add lightweight Vitest/Jest + Supertest coverage under server/src/__tests__/ and component tests under client/src/__tests__/; document any manual steps (e.g., portal link generation, uploads).

Commit & Pull Request Guidelines

• Use Conventional Commits (feat:, fix:, chore:, docs:) and keep messages scoped to one change.
• PRs should describe intent, impacted endpoints/pages, and testing done; attach screenshots for UI tweaks and list any migration or env var changes.
• When Prisma schema changes, include migration SQL or regeneration steps and note required data/backfill work.

Security & Configuration Tips

• Keep secrets in server/.env and UI env hints in client/.env.local; never commit them. Ensure DATABASE_URL, JWT_SECRET, and PORTAL_URL are set before running.
• Uploaded files under server/uploads/ are served statically; avoid committing generated assets and clear sensitive data before sharing logs.