67 lines
5.4 KiB
Markdown
67 lines
5.4 KiB
Markdown
# 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.
|