rhl-lieferscheine/AGENTS.md

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