lcbp3.np-dms.work/.github/copilot-instructions.md

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.