# rhl-lieferscheine

## Tech Stack
- Frontend: Next.js 16 App Router, React 19, JavaScript/JSX, Tailwind CSS 4
- Backend: Next.js Route Handlers on Node.js 22-slim
- Database: MongoDB 7 via Mongoose 9
- Auth: Signed JWT session cookie (`auth_session`), `bcryptjs`, RBAC roles `branch | admin | superadmin | dev`
- Deployment: Docker Compose with NAS mount, GitLab CI/CD planned

## Conventions
- Read `~/.codex/docs/NEXTJS_CONVENTIONS.md` for code conventions.
- Read `~/.codex/docs/DEFAULT_STACK.md` for stack defaults.

## Project-Specific Rules
- Keep owner-facing conversation in German.
- Write source code, comments, tests, and project docs in English.
- Keep user-facing UI text in German.
- Treat `Docs/` as the canonical project documentation directory for this repository.
- Do not overwrite existing `Docs/` content without explicit approval. `Docs/frontend-ui.md` may contain local changes and must stay untouched unless the user asks for edits there.
- Keep the product scope intentionally pragmatic. Do not reintroduce dropped feature families such as large dashboards, saved searches/bookmarks, or an in-app PDF viewer without approval.
- Treat Qsirch as required for the target environment. Do not plan production rollout around filesystem search alone.
- Respect the current access model: one account per branch, branch users only see their own branch, elevated roles may work across branches, and only `superadmin` / `dev` may manage users.
- Follow the established delivery flow: work ticket-by-ticket, run `npx vitest run` and `npm run build` before new implementation steps, stop for local/server verification before updating docs.
- When docs are requested, write full-file outputs instead of diff snippets.

## Ticket Naming
- Prefix: RHL
- Format: `RHL-XXX`

## Branch And MR Naming
- Branch: `type/rhl-xxx-slug`
- MR title: `RHL-XXX type(scope): summary`
- Types: feat, fix, refactor, docs, chore, style, test, perf, ci, build

## Commands
- Install dependencies: `npm install`
- Start dev server: `npm run dev`
- Run tests once: `npx vitest run`
- Watch tests: `npm run test:watch`
- Build production bundle: `npm run build`
- Start production server: `npm run start`
- Lint repository: `npm run lint -- .`
- Validate environment: `node scripts/validate-env.mjs`
- Start local Docker stack: `docker compose -f docker-compose.yml -f docker-compose.local.yml up --build`
- Start server-like Docker stack: `ENV_FILE=.env.server docker compose -f docker-compose.yml up -d --build`
- Run manual API smoke flow: `docker compose exec app node scripts/manual-api-client-flow.mjs --baseUrl=http://127.0.0.1:3000 --username=<user> --password=<pw> --branch=<branch>`

## Key Paths
- `app/` - routes, protected/public app structure, route handlers
- `components/` - UI building blocks
- `lib/` - domain logic, API client helpers, auth/storage/search helpers
- `models/` - MongoDB user model
- `scripts/validate-env.mjs` - environment validation entrypoint
- `scripts/manual-api-client-flow.mjs` - manual smoke validation helper
- `Docs/` - existing product and operational documentation
- `docker-compose.yml` and `docker-compose.local.yml` - runtime definitions

## Stop And Ask
Escalate before continuing when the task touches:
- architecture or scope changes
- auth, RBAC, or security-sensitive behavior
- database schema or MongoDB operational topology
- CI/CD, deployment automation, reverse proxy, or HTTPS rollout
- secrets, credentials, or Qsirch integration details