# Copilot instructions for DMS repository

This file contains short, actionable guidance for AI coding agents working in this repository. Keep edits small and focused; prefer non-invasive changes and always run the project's health checks after edits.

Summary (one line):
- Monorepo-style Dockerized DMS app: Node (ESM) backend (Express + Sequelize + MariaDB), Next.js frontend, n8n workflows, nginx/NPM reverse proxy, and various DB admin containers.

What to read first (order matters):
1. `README.md` (root) — high-level architecture and host paths used on QNAP (/share/Container/dms and /share/dms-data).
2. `docker-compose.yml` — service boundaries, env var conventions, mounted volumes, and healthchecks.
3. `backend/README.md` and `backend/package.json` — backend runtime (Node >=20, ESM), start/dev scripts, and important env names (DB_*, JWT_*).
4. `frontend/package.json`, `frontend/next.config.js`, `frontend/middleware.ts` — Next.js routes and auth cookie usage.

Quick architecture notes (why things are structured this way):
- Containers are intended to run on QNAP Container Station; many volumes map host paths under `/share/Container/dms` and `/share/dms-data` for persistent storage and uploads.
- Backend is ESM Node app with Sequelize connecting to MariaDB. No project-level `.env` — environment is provided by `docker-compose.yml` or Container Station.
- Frontend is Next.js (server+client) running on port 3000. Middleware enforces cookie-based auth (`access_token`).
- Reverse proxy (NPM) and nginx landing are used to expose services; ensure `TRUSTED_PROXIES`, `ROOT_URL`, and proxy headers are configured when editing networking code.

Important developer workflows (commands & checks):
- Backend dev server:
  - npm run dev (in `backend/`) — nodemon watches `src` and restarts. Port from `PORT` env (default 3001).
  - npm run health (in `backend/`) — quick healthcheck: fetches /health.
- Frontend dev server:
  - npm run dev (in `frontend/`) — next dev on port 3000.
- Docker: use `docker-compose up -d` on the host (QNAP) to recreate services. On local dev, mount source to container as `docker-compose.yml` shows.

Project-specific conventions and patterns:
- No `.env` files in repo; service environment is provided in compose and expected on host. Do not introduce secrets into repository; use compose or host secrets.
- Ports: backend 3001, frontend 3000. Health endpoints: `/health` for both services.
- File uploads are module-scoped: upload endpoint is `POST /api/v1/uploads/:module/:refId` and allowed `module` values are in README (rfa, correspondence, drawing, document, transmittal).
- RBAC: permission strings like `rfa:create` and middleware `requirePerm('...')` (see `backend/middleware/permGuard.js`). Prefer existing middleware and permission helpers rather than inlining checks.
- Views endpoints require `?project_id=` for scoped queries and enforce `projectScopedView('<module>')` policy.

Key files and directories to reference for edits or feature additions:
- `backend/src/` — controllers, routes, middleware, models (Sequelize). Look for `index.js`, `routes/`, `models/`, `middleware/`.
- `frontend/app` and `frontend/page.jsx` — Next.js app routes and top-level page.
- `docker-compose.yml` — service shapes, volumes, env var names, and healthchecks (use this to know what variables to set).
- `README.md` (root) and `backend/README.md` — canonical list of endpoints and env vars.

Testing and validation checklist for code changes:
- Backend: run `npm run lint` (placeholder) and `npm run health` in `backend/`. Start nodemon and ensure `/health` returns OK and DB connection works.
- Frontend: run `npm run dev` and confirm middleware redirects unauthenticated users to `/login` when visiting protected routes (see `middleware.ts` matcher).
- Docker compose: after edits to services or env vars, run `docker-compose up -d --build` and watch healthchecks. Check mapped host paths under `/share/Container/dms`.

Common pitfalls to avoid (from repo patterns):
- Do not hardcode secrets (JWT secrets, DB passwords) into code or repo files — they appear in compose for local deployment but should not be committed for production.
- File permissions: many volumes expect certain UID/GID (e.g., `USER_UID=1000`). Ensure the container user has write permission for uploads and logs.
- Large file uploads: proxy (NPM/nginx) may block big uploads; remember to check proxy `client_max_body_size` or NPM upload limits when debugging upload issues.

If you change routing, auth, or upload behavior:
- Update `frontend/middleware.ts` if protected path patterns change.
- Update backend `routes/` and ensure RBAC middleware usage follows `requirePerm` and `projectScopedView` patterns.
- Run both services and test a full upload flow: login -> upload file -> download -> list files.

When you need more context, open these files first:
- `docker-compose.yml` (service boundaries & env names)
- `backend/README.md` (endpoint list & env examples)
- `backend/src/index.js` (app bootstrap & middleware wiring)
- `backend/src/middleware/permGuard.js` (RBAC enforcement)
- `frontend/middleware.ts` (auth enforcement for routes)

If the repo already contains a `.github/copilot-instructions.md`, merge rather than replace; preserve any specific workflow steps.

Feedback request
- Is there any additional developer workflow or file path you'd like included (build scripts, CI, or QNAP-specific steps)? If yes, point me to the file(s) and I'll integrate them.