# AGENTS.md — dashback (Express API)

ESM (`type: module`), Express 5, Node. Depends on `libdashstore` via `file:../dashdbschema`.

## Architecture

- Entry: `src/index.js` → `src/api/index.js` (`startApi`/`stopApi`, `loadRoutes()` walks `src/api/routes/**/*.js` → `register(app, basePath)`).
- Each route file owns its `@openapi` JSDoc + `*ErrorStatus(err)` mapper + `requireSelectedCompany(req)`. Source of truth is code.
- DB: `src/db/store.js` lazy singleton provider+store (timing logs `libstore <ns>.<method>`); `src/db/<domain>.js` are thin wrappers around `store.<ns>.<method>`.
- Config: `src/config/env.js` (`.env`; `PORT` 4208, `HTTPS_PORT`, `GOOGLE_CLIENT_ID`, `JWT_SECRET`, `CORS_ORIGINS`, `DB_PROVIDER=mssql|sqlite`, `SQLITE_PATH`, `MSSQL_*`).
- Auth: `src/api/middleware/auth.js` (Google SSO + JWT cookie, `req.user.{id,selectedCompanyId}`); allowlist via `scripts/manageUsers.js`.
- SSE: `src/api/sse.js` (`emit`), `routes/events.js`. Stock adjust emits `stock`, `ledger`, `articles`, `article-<sku>`.
- `src/v1/` legacy POS compat — don't touch unless task is POS. `quixpos2jtl/` is a separate Electron/CLI bridge — ignore unless task mentions JTL.
- Docs: generated, never hand-edit — see below. Interactive API documentation & tester served under `/docs/` (`/docs/openapi.json`).

## Build / Test / Docs

```bash
cp .env.example .env && npm install
npm start                          # PORT 4208 (HTTPS 8443)
npm run docs:api                    # regenerates docs/api/routes.md + docs/api/routes-all.md + docs/api/routes/ + openapi.json
npm run manage-users                # email allowlist
```

- No `npm test`. Verify with syntax check or a self-exiting run on a **different port**; never leave a listener running — user keeps their own dev server.
- Store contract lives in sibling repo: `../dashdbschema/API.md` + `API.<module>.md`, `../dashdbschema/README.md`. Read-only.

## Conventions

- Sibling repos (`../dashdbschema`, `../dashfront`) are **read-only**: may read docs/code + `git -C ../<repo> log --oneline -20`, never write/install/start. Missing contract → ask human, don't guess. No fallbacks/defaults. See `.cursor/rules/sibling-repos.mdc`, `.cursor/rules/dont-start-the-API-server.mdc`.
- After any route change run `npm run docs:api`. Docs index: `docs/api/README.md`.
- HTTP mapping per route file: `No company selected→400`, `Not authorized→403`, `*not found→404`, validation (`includes()`)→400, uniqueness/in-use→409, else 500 + `console.error`. `Stock tracking is disabled…→409`.
- Keep error strings stable/greppable — mapping depends on exact messages from `libdashstore`.
- Stock/ledger invariants belong in `dashdbschema/src/store/`, not routes, so both `stock.adjust` and direct `ledger.add` are covered.
- Full backend/store conventions: `.agents/skills/project-overview/SKILL.md`.