# Repository Guidelines

## Project Structure & Module Organization
Group backend features by domain for clarity. TypeScript sources live in `src/`, with feature modules inside `src/modules/<domain>` (such as `src/modules/inventory`). Shared helpers stay in `src/common`, configuration code in `src/config`, and migration SQL in `migrations/`. Mirror the module layout under `test/unit` and `test/integration` so every service has a matching spec file (`test/inventory/inventory.service.spec.ts`).

## Build, Test, and Development Commands
Install dependencies once per clone with `npm install`. Start the API locally using `npm run start:dev`, which launches the NestJS server with live reload. Build distributable assets through `npm run build`, then sanity-check the compiled bundle via `npm run start:prod`. Run all Jest suites with `npm run test` and enforce linting rules with `npm run lint`. After adding migrations, confirm they apply cleanly using `npm run typeorm migration:run`.

## Coding Style & Naming Conventions
This project relies on ESLint and Prettier; run `npm run lint -- --fix` before committing to keep formatting consistent. Use 2-space indentation, `camelCase` for variables, `PascalCase` for classes, and `kebab-case` for file names (`inventory-service.controller.ts`). Centralize environment variable access inside `src/config/env.ts` instead of scattering `process.env` reads throughout the codebase.

## Testing Guidelines
Author Jest unit specs beside each service or controller (`*.spec.ts`) and place broader API checks in `test/integration` using the `*.e2e-spec.ts` suffix. Aim for at least 80% line coverage, keeping reusable fixtures under `test/fixtures`. When code touches persistence, add a migration smoke test that boots an in-memory database via `npm run test -- --runInBand`. Any skipped tests must include a TODO and linked follow-up issue.

## Commit & Pull Request Guidelines
Follow Conventional Commits (`feat(inventory): add shelf life checks`) and keep each commit focused on one concern. Pull requests should ship with a concise summary, linked issue, evidence of manual or API testing, migration notes when applicable, and the latest `npm run test` results. Tag a maintainer for the impacted module and call out breaking API changes in the PR title.

## Security & Configuration Tips
Never commit real secrets; store local overrides in `.env.local` and refresh `env.example` whenever variables change. Review `config/default.ts` before altering defaults, and document new external integration keys in the PR description. Handle any personal data through DTOs that mask sensitive fields before logging or returning responses.