# Repository Guidelines

## Project Structure & Module Organization
- `node-api/`: Node.js Express service (ES modules).
  - `src/app.js`: Express app bootstrap; static files served from `public/`.
  - `src/routes/`: API (`api.js`) and RADIUS hooks (`radius.js`).
  - `src/services/`: DB (`db.js`), RADIUS/CoA (`radius.js`).
  - `src/utils/attrs.js`, `src/sse.js`.
  - `index.js`: entrypoint (schema ensure + server).
- `frontend/`: Vue 3 + Vite SPA.
  - `src/`: `App.vue`, components, `styles.css`.
  - `index.html` and built assets in `dist/` (ignored).
- `postgres/init/`: SQL schema files.
- `freeradius/`: server configuration used by docker.
- `docker-compose.yml`: local stack (node, postgres, freeradius).

## Build, Test, and Development Commands
- `npm run dev`: build frontend, start full stack with Docker.
- `npm run restart`: rebuild + recreate containers.
- `npm run logs`: follow service logs; `npm run down`: stop stack.
- Frontend dev (hot-reload): `npm --prefix frontend run dev` (proxy to `:3000`).
- Manual guest cleanup: `POST /api/guests/disable-yesterday`.

## Coding Style & Naming Conventions
- JavaScript/Node (ESM), Vue SFCs, 2-space indent, semicolons, single quotes.
- Filenames: kebab-case for files, PascalCase for Vue components, camelCase for vars/functions.
- Keep modules small and colocate helpers in `src/utils/` or `src/services/`.
- No formatter configured; match existing style.

## Testing Guidelines
- No test harness checked in. If adding tests:
  - API: Jest + Supertest under `node-api/tests/`.
  - Frontend: Vitest under `frontend/src/__tests__/`.
  - Prefer small, fast unit tests; name with `*.test.js`.

## Commit & Pull Request Guidelines
- Follow Conventional Commits where practical (e.g., `feat:`, `fix:`, `chore:`, `style:`). Examples in history: `chore(git): …`, `style(ui): …`.
- PRs should include:
  - Summary, rationale, and scope.
  - Linked issue (if any) and screenshots/GIFs for UI changes.
  - Notes on migrations (`postgres/init`) or env changes.

## Security & Configuration Tips
- Do not commit secrets; `.env` is ignored. Configure `RADIUS_SECRET`, PG creds, VLAN/bandwidth via env.
- DB schema is auto-ensured at startup; initial SQL runs from `postgres/init/` when the volume is new.
- SSE endpoints stream events at `/api/events`; be mindful of long-lived connections.