# Repository Guidelines ## Project Structure & Module Organization This is a pnpm workspace. The React Router web runtime lives in `apps/web`, with source in `apps/web/app` and static assets in `apps/web/public`. API and worker runtimes live in `apps/api` and `apps/worker`. Shared packages live under `packages/*`, including `@toolctrl/db`, `@toolctrl/config`, `@toolctrl/url`, `@toolctrl/foundation`, and UI/view-model packages. Prisma schema and migrations are in `prisma/`. Repository scripts and verification gates are in `scripts/`. Before substantial feature work, read `docs/agent-entrypoints.md`. If a change adds or imports a feature, changes admin-managed behavior, provider credentials, workers, or proprietary logic, update the relevant `docs/feature-manifests/*.json` first. ## Build, Test, and Development Commands - `pnpm install`: install workspace dependencies. - `pnpm run dev`: start the web runtime through `@toolctrl/web`. - `pnpm run typecheck`: generate Prisma/types and run TypeScript project checks. - `pnpm run lint`: run ESLint across TypeScript and TSX files. - `pnpm run test`: run the root Vitest/script test suite in non-watch mode. - `pnpm run build`: generate Prisma and build the web client/server. - API/worker changes also need `pnpm --filter @toolctrl/api build` or `pnpm --filter @toolctrl/worker build`. - `pnpm run verify:i18n`, `pnpm run verify:phase-c-boundaries`, `pnpm run test:hot-swap`: run focused Phase C gates. - `pnpm run verify:api-inventory`, `pnpm run verify:openapi-security`: check API route and OpenAPI drift. - `pnpm run verify:deploy-workflow`, `pnpm run verify:docker-baseline`, `pnpm run verify:production-seed-artifact`: verify deploy workflow, Docker baseline, and seed artifact contracts before deploy changes are pushed. - `pnpm exec vitest run apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts`: verify API access docs after route changes. - `pnpm exec vitest run apps/web/app/utils/session.server.test.ts apps/web/app/utils/session-csrf-sweep.test.ts apps/api/src/csrf-inventory.test.ts`: verify CSRF inventory after mutating route changes. - `pnpm run verify:permission-matrix`: verify role and permission documentation after permission catalog changes. ## Coding Style & Naming Conventions Use TypeScript and React Router conventions already present in `apps/web/app`. Prefer workspace package boundaries over direct cross-runtime imports. Use `@toolctrl/*` package names for shared modules. Route and UI links must use canonical host-aware helpers from `@toolctrl/url` or local wrappers such as `appPath`, `adminPath`, `apiPath`, and cross-host helpers. Use `UrlUtils.getModulePath(...)` for internal tenant module navigation only. Boundary defaults: server DB access goes through `@toolctrl/db/client.server`; environment reads go through `@toolctrl/config`; queue names and payloads come from `@toolctrl/queue`; API app composition stays in `apps/api/src/app.ts`; worker processors stay in `apps/worker`. ## Testing Guidelines Tests use Vitest and Testing Library. Keep tests next to the code they cover with names like `*.test.ts` or `*.test.tsx`. Add focused tests for routing, permissions, boundaries, idempotency, and tenant-scope behavior when changing those areas. For new or changed `POST`, `PATCH`, or `DELETE` web/API routes, update `docs/security/csrf-inventory.md` when the protection surface changes. Role or permission changes should update `docs/roles-matrix.md` and the relevant seed/package tests. ## Commit & Pull Request Guidelines Use concise imperative commit messages such as `fix: canonicalize tenant routes` or `feat: add foundation audit boundary`. Keep commits logically scoped. PRs should describe behavior changes, list verification commands run, mention migrations or config changes, and include screenshots for visible UI changes. ## Security & Configuration Tips Do not read secrets directly in UI code. Use `@toolctrl/config` loaders and server-only boundaries. Tenant-scoped data access must flow through explicit DB/package helpers and preserve tenant filters.