Skylar Grant
817fa47edd
All checks were successful
Build and push image / build (push) Successful in 13s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
48 lines
4.0 KiB
Markdown
48 lines
4.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
Context for Claude Code sessions in this repo. Keep this short. Longer notes live in `docs/`.
|
|
|
|
## Project
|
|
|
|
A help desk dashboard for ManageEngine ServiceDesk Plus Cloud (`ithelp.mainecc.edu`). It's a Node/Express server, shipped as the Docker image `v0idf1sh/sdp-dashboard`, running behind Nginx Proxy Manager with an MCCS IP allow list. Each user signs in with their own Zoho account; the session is an encrypted cookie. `.env` sets the defaults (central region: KVCC, EMCC, CMCC, MCCS); each user can override region, timing, weather and hidden panels in Settings, saved on the server by Zoho email in `DATA_DIR` (a Docker volume).
|
|
|
|
- **Goal and next steps:** per-user settings (built, needs live checks) and panel modules. See `docs/ROADMAP.md`.
|
|
- **Decisions, API gotchas and known issues:** `docs/NOTES.md`. Read it before touching any SDP query.
|
|
- **Latest session summary and handoff:** `SESSION.md`.
|
|
|
|
## Run
|
|
|
|
```text
|
|
npm install
|
|
npm run app # node src/server.js from the repo root; .env lives in the repo root
|
|
```
|
|
|
|
The app is served at <http://localhost:3000>. `.env` needs `CLIENT_ID`/`CLIENT_SECRET` from a Zoho **Server-based Application** client with `http://localhost:3000/auth/callback` as a redirect URI, plus a `SESSION_SECRET` of 32 or more characters.
|
|
|
|
Releases: push a `v*-prod*` tag. `.gitea/workflows/docker.yml` builds and pushes the image; the VPS is updated by hand.
|
|
|
|
## Layout
|
|
|
|
- `src/server.js`: reads `.env`, holds the region `settings` and `timing`, and starts Express.
|
|
- `src/auth.js`: Zoho web OAuth (authorization URL, code exchange, renewal, revoke, user info).
|
|
- `src/session.js`: the encrypted session cookie and the `requireSession` middleware, which renews the access token when it's due.
|
|
- `src/routes.js`: `/auth/*` (login, callback, logout) and `/api/*` (session, settings, names, closed, workload, weather; all need a sign-in).
|
|
- `src/settings.js`: per-user settings: validation, `LIMITS`, merging over the `.env` defaults. `src/store.js` is the JSON file store under it.
|
|
- `src/names.js`: shared cache of site/group/technician names for the settings suggestions.
|
|
- `src/places.js`: the weather locations people can pick.
|
|
- `src/tickets.js`: all SDP queries (closed feed, status table, closed today, unassigned). A 401 from SDP is rethrown so the route signs the user out.
|
|
- `src/weather.js`: OpenWeatherMap, cached for 10 minutes per zip and shared by all users.
|
|
- `src/public/index.html`: the whole front end in one file (inline CSS and JS, no build step). It runs the polling timers, keeps the closed feed, and has the settings dialog.
|
|
- `Dockerfile`, `docker-compose.yml` (example for the VPS), `.gitea/workflows/docker.yml`.
|
|
|
|
## Working agreements
|
|
|
|
- Never print or commit `.env` values (Zoho client secret, `SESSION_SECRET`, OpenWeatherMap key). Redact them when inspecting.
|
|
- Never send Zoho tokens to the page or put them in logs. They stay inside the encrypted cookie and server memory for the length of a request.
|
|
- There are no automated tests yet. Verify server logic by stubbing `axios.get` and `axios.post`. Resolve axios from the project with `require.resolve('axios', { paths: [dir] })` so the stub hits the same instance. Verify the page by evaluating its `<script>` with stubbed `document`, `fetch`, `location` and `history`, or by taking a screenshot with headless Edge.
|
|
- The sandbox can't bind TCP ports, but it can listen on a unix socket with a short relative path (`cd` to the scratchpad and listen on `x.sock`). To run `server.js` end to end, patch `express.application.listen`. Docker isn't available in the sandbox.
|
|
- Match the existing style: 4-space indent and CommonJS on the server, 2-space indent in `index.html`, lowercase `//` comments explaining why rather than what. Some files have CRLF line endings, so use the Edit tool rather than sed for multi-line changes.
|
|
- Keep the core closed-ticket watcher (feed and ding) working and on by default.
|
|
- Don't commit unless asked. Commit messages end with the Co-Authored-By line for Claude.
|
|
- Record new decisions and gotchas in `docs/NOTES.md`, and move roadmap items as they're done.
|