dashback/AGENTS.md

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

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.