workorder-desk/SPEC.md

Field Service Work Order Management — Technical Specification

Version: 1.2 Status: Implementation contract Last Updated: 2026-08-16

Incorporates findings from two adversarial reviews and two design reviews of v1.0 Draft. v1.2 rebrands the generic item model as work orders for field service and maintenance teams.

1. Overview

1.1 Purpose

A production-oriented MERN (MongoDB, Express, React, Node.js) application purpose-built as a work-order management system for field service and maintenance teams. Technicians log jobs, track them through status and priority, and close them out; a dispatcher (admin) oversees every work order and the team. It keeps the production-grade baseline — layered architecture, cookie-based auth, typed data layer — and is not the smallest possible todo app.

1.2 Goals

• Working, deployable app out of the box (seeded admin + user).
• Domain-shaped work-order model: status/priority lifecycle instead of generic items.
• Layered backend and feature-sliced frontend.
• JWT in httpOnly cookies, refresh rotation with family reuse detection.
• Typed frontend data layer (wrapped fetch + TanStack Query).
• Unit + integration tests with coverage gates.
• Reproducible local + Docker setup.
• Structured logging, validation, and a closed error catalog.

1.3 Non-Goals (v1)

• Real-time (WebSockets).
• Multi-tenant / org isolation.
• Payments.
• File uploads / object storage (no stub interface).
• Internationalization (en-US only).
• Audit-log product UI (removed from admin persona).
• Work-order reassignment or scheduling: the creator owns a work order in v1 (dispatcher reassignment is a v2 concern).
• Multi-document Mongo transactions (standalone Mongo).
• CSRF tokens (same-origin deployment; see §8.5).

1.4 Personas

Persona	Role	Primary needs
Dispatcher (admin)	Full access	Manage users and roles, oversee and search all work orders, view metrics
Technician (user)	Standard user	Log, update, and close own work orders; manage profile
Anonymous visitor	Unauthenticated	Register, login, request/complete password reset

2. Key Decisions

Decision	Options considered	Choice	Why
Auth transport	Bearer in memory vs httpOnly cookies	httpOnly cookies + SameSite=Lax	XSS cannot read tokens; see ADR-0001
Deploy topology	Split origins vs reverse-proxy same origin	Same origin: Vite proxy (dev), nginx (prod/compose)	Lax cookies work; CSRF tokens out of scope
HTTP client	fetch vs axios	Wrapped fetch	No extra dep; tests mock fetch
Lockfile	npm vs yarn	package-lock.json only	npm workspaces default
Monorepo	workspaces vs turborepo	npm workspaces	Simpler for two packages + packages/shared
Schemas	duplicate vs shared package	packages/shared zod + types	Prevents envelope/DTO drift
Pagination	cursor everywhere vs mixed	Cursor on /work-orders and /admin/work-orders; offset on /admin/users	Users table is small; work orders follow NFR-2
Admin all work orders	scope= vs dedicated route	No scope. /work-orders is owner-only. /admin/work-orders is global	Removes list IDOR
Refresh storage	embed on User vs collection	RefreshSession collection + familyId	Multi-device + reuse ⇒ revoke family
Refresh signing	opaque vs JWT	Opaque 32-byte, SHA-256 at rest	Drop REFRESH_SECRET
First admin	first-register vs seed	Idempotent npm run seed	Deterministic local/CI credentials
User disable	isActive vs deletedAt vs both	isActive only on User	One state machine
Work order delete	hard vs soft	Soft deletedAt; GET 404; lists exclude	Matches WO-7
Mongo txns	replica set vs none	None in v1	Compose Mongo is standalone
Perf SLO	p95 < 200 ms @ 1k conc.	Dropped from v1 DoD	bcrypt 12 cannot meet it; untestable
Register enumeration	hide vs 409	409 EMAIL_TAKEN	Starter documents this leak
Lockout status	423 vs 429 vs generic 401	Generic 401 AUTH_GENERIC	Avoids lockout oracle
HTTP access JWT role	trust JWT role vs DB	Load user every request; authorize from DB	Demotion/deactivation take effect immediately

ADRs: docs/adr/0001-jwt-httpOnly-cookies.md, docs/adr/0002-npm-workspaces.md.

3. Tech Stack

Layer	Technology	Version
Runtime	Node.js	20 LTS
Language	TypeScript	5.x
API	Express	4.x
Database	MongoDB	7.x
ODM	Mongoose	8.x
Frontend	React	18.x
Build	Vite	5.x
Routing	React Router	6.x
Server state	TanStack Query	5.x
HTTP	wrapped fetch	—
CSS	Tailwind CSS	3.x
Validation	zod (in packages/shared)	3.x
Auth	JWT HS256 + httpOnly cookies	—
Passwords	bcrypt cost 12	5.x
Tests	Vitest + Supertest + Testing Library	2.x / 7.x / 14.x
Logs	pino	9.x
Containers	Docker + compose	24.x / 2.x
Lint / format	ESLint 9 flat + Prettier 3

Pin exact versions in the root package-lock.json. Do not commit yarn.lock.

4. Architecture

Browser (one origin)
  Vite :5173  ──proxy /api,/health,/ready──►  Express :4000  ──►  MongoDB :27017
  nginx :80   ──same paths──────────────────►  Express :4000  ──►  MongoDB

4.1 Backend dependency direction

routes → middleware → controllers → services → repositories → models

• Controllers map HTTP ↔ DTO. No business rules, no Mongoose.
• Services take an Actor { id, role } (never req/res).
• Repositories own queries. Default work-order reads add deletedAt: null.
• Models export schemas + TS types. Only repositories import mongoose at runtime.
• import/no-cycle is required. v1 does not use multi-document transactions.

4.2 Middleware order (app.ts)

1. trust proxy from TRUST_PROXY_HOPS (default 0)
2. request-id (X-Request-Id, generate UUIDv4 if missing/invalid)
3. pino-http (redact cookies/passwords/hashes)
4. helmet (API JSON CSP: default-src 'none')
5. compression
6. cors (origin = CORS_ORIGIN list, credentials: true; reject * if credentials)
7. cookie-parser (COOKIE_SECRET)
8. json (limit: 32kb) — no urlencoded (blocks HTML-form CSRF)
9. hpp
10. recursive $ / __proto__ / constructor rejection on body + query
11. global rate limit
12. routes
13. 404 handler
14. error middleware

4.3 Frontend layering

pages → features/{auth,workOrders,admin,profile} → components (primitives) → api/client → lib

• Query hooks live in features/*/queries.ts, not in api/.
• React Router loaders are not used. TanStack Query owns server state.
• ProtectedRoute / AdminRoute are UX only; API is the authority.
• Bootstrap: GET /users/me; 401 → anonymous. 401 interceptor single-flights POST /auth/refresh then retries once.

5. Functional Requirements

5.1 Authentication & authorization

ID	Requirement
AUTH-1	Register { email, password, name }. Email trim+lowercase. Name 1–80 chars. Password 8–72 chars, ≥1 letter, ≥1 number. Default role=user, isActive=true. Duplicate email → 409 EMAIL_TAKEN. Success 201 + set session cookies (auto-login).
AUTH-2	Login { email, password }. Unknown email, bad password, inactive user → 401 AUTH_GENERIC after dummy bcrypt. Success 200 + cookies, set lastLoginAt, reset failedLoginCount.
AUTH-3	Access cookie access_token: JWT HS256, claims sub, role, sid, iss, aud, iat, exp (15m). httpOnly, SameSite=Lax, Secure iff NODE_ENV=production, Path=/, Max-Age=900.
AUTH-4	Refresh cookie refresh_token: opaque 32 bytes, SHA-256 stored on RefreshSession, 7-day TTL, Path=/api/v1/auth, same flags as access, Max-Age=604800. Rotation keeps familyId. Reuse of a used/revoked token outside a 10s grace window revokes the family and returns 401 REFRESH_REUSE. Multi-device = many families.
AUTH-5	authenticate verifies JWT, loads user by sub, rejects missing/inactive, attaches Actor from DB (id, role). Invalid ObjectId params → 400 VALIDATION_ERROR.
AUTH-6	POST /auth/logout revokes the current session (sid or presented refresh). Clears both cookies (Max-Age=0). POST /auth/logout-all revokes every family for the user.
AUTH-7	Forgot-password always 200 + generic message. Token: 32 random bytes, SHA-256 at rest, TTL 1h, replaces previous. MVP mailer logs a redacted URL (token replaced with [redacted]). Reset page /reset-password?token=. Successful reset revokes all families, clears reset fields, sets cookies.
AUTH-8	Profile name via PROFILE-2. Password change via PROFILE-3 (same password rules).
AUTH-9	Roles admin | user. Only admin can change roles. Cannot target self. Cannot demote the last remaining admin (count admins, reject). Reload DB role (AUTH-5). Demotion revokes that user’s refresh families.
AUTH-10	Owner/ids come from Actor, never from the body. Write schemas .strict().
AUTH-11	After 5 failed logins for an existing user within 15 minutes, set lockedUntil = now+15m. Unknown emails do not increment. Reset counter on success. Locked users still receive 401 AUTH_GENERIC. IP limiter is separate (429 RATE_LIMITED).

5.2 Work orders

A work order is a job logged by a technician and tracked from request to completion. The creator is the owner; dispatchers see everything via /admin/work-orders.

ID	Requirement
WO-1	Fields: title (job summary) 3–100, description optional ≤2000 (job details/notes), priority low|medium|high (default medium), status pending|in_progress|done (default pending), owner, version (starts at 1), createdAt, updatedAt, deletedAt?.
WO-2	GET /work-orders returns only owner = actor.id. No scope param.
WO-3	Cursor pagination: default limit=20, max 100. Sort createdAt desc, _id desc. Cursor = HMAC-SHA256(payload, COOKIE_SECRET) + payload { createdAt, id }. Tamper → 400. Last page: nextCursor: null.
WO-4	Filter status and priority. Search title regex-escaped, case-insensitive, max 64 chars.
WO-5	Create → 201 full WorkOrderPublic. version=1. Owner = actor.
WO-6	Update owner or admin. version required. Stale → 409 CONFLICT_VERSION. Predicate { _id, version, deletedAt: null } then $inc.version.
WO-7	Soft delete owner or admin. version required. 204 empty body. Already deleted → 204 (idempotent). GET-by-id and lists hide deletedAt != null. No undelete.
WO-8	Zod .strict() on writes before services.
WO-9	See WO-6/7. Create version=1. Custom field, mongoose versionKey: false.
WO-10	GET /work-orders/:id owner or admin; anyone else or deleted → 404. Invalid id → 400.

5.3 Admin

ID	Requirement
ADM-1	GET /admin/users admin only. Offset page, default 1, limit 20 max 100. Search name+email, escaped, max 64. Filter role.
ADM-2	PATCH /admin/users/:id/role { role } strict enum. Not self. Not last admin.
ADM-3	GET /admin/work-orders all non-deleted work orders, cursor pagination.
ADM-4	GET /health public { status: "ok" }, no internals, excluded from rate limit. GET /ready public, pings Mongo, 503 if down. GET /admin/metrics admin { users, workOrders, uptimeSeconds }.
ADM-5	PATCH /admin/users/:id/status { isActive }. Not self. Deactivate revokes that user’s families.

5.4 Profile

ID	Requirement
PROFILE-1	GET /users/me → UserPublic.
PROFILE-2	PATCH /users/me { name } only.
PROFILE-3	POST /users/me/password { currentPassword, newPassword }. Wrong current → 401 AUTH_GENERIC. Success revokes other families, rotates current session, sets cookies.

5.5 Frontend routes

Route	Access	Notes
/	Public	Landing
/login, /register	Public	Redirect to /app if already authed
/forgot-password	Public	Request form
/reset-password	Public	Token from ?token=
/app	Protected	Redirects to /app/work-orders
/app/work-orders	Protected	List + filter (status/priority) + search + cursor
/app/work-orders/new	Protected	Create
/app/work-orders/:id	Protected	Detail / edit / delete; 409 reload
/app/profile	Protected	Name + password
/app/admin	Admin	Users, role, status
*	—	404 page

UI gates are not authorization.

6. API Contract

Public (unversioned): GET /health, GET /ready

App base: /api/v1

Auth cookies: access_token, refresh_token (see AUTH-3/4).

6.1 Envelopes

type SuccessEnvelope<T> = { success: true; data: T };
type ErrorEnvelope = {
  success: false;
  error: { code: ErrorCode; message: string; details?: { field: string; message: string }[] };
  requestId: string;
};
type ErrorCode =
  | 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND'
  | 'CONFLICT_VERSION' | 'RATE_LIMITED' | 'ACCOUNT_LOCKED'
  | 'AUTH_GENERIC' | 'EMAIL_TAKEN' | 'REFRESH_REUSE' | 'INTERNAL';

204 has no body. Auth failures that must not distinguish cause use AUTH_GENERIC + 401. ACCOUNT_LOCKED is reserved but unused on the wire in v1 (lockout still enforced).

6.2 Status map

HTTP	Code	When
200/201	—	Success envelope
204	—	Soft delete
400	VALIDATION_ERROR	Zod, bad ObjectId, bad cursor, search too long
401	UNAUTHORIZED	Missing/invalid/expired access token
401	AUTH_GENERIC	Login/password failures, inactive, locked
401	REFRESH_REUSE	Reused refresh family revoked
403	FORBIDDEN	Authenticated but not permitted (incl. last-admin, self-role)
404	NOT_FOUND	Missing or hidden work order/user
409	CONFLICT_VERSION	Stale work order version
409	EMAIL_TAKEN	Register duplicate
429	RATE_LIMITED	IP / route limiter
500	INTERNAL	Unexpected; no stack unless DEBUG_ERRORS=true
503	INTERNAL	/ready when Mongo down (body { status: "degraded" })

6.3 DTOs

type UserPublic = { id: string; email: string; name: string; role: 'admin' | 'user'; createdAt: string; updatedAt: string };
type UserAdmin = UserPublic & { isActive: boolean; lastLoginAt: string | null };
type WorkOrderPublic = {
  id: string; title: string; description: string | null;
  priority: 'low' | 'medium' | 'high';
  status: 'pending' | 'in_progress' | 'done';
  owner: { id: string; name: string; email: string };
  version: number; createdAt: string; updatedAt: string;
};
type CursorPage<T> = { items: T[]; nextCursor: string | null };
type OffsetPage<T> = { items: T[]; page: number; limit: number; total: number };

Never return passwordHash, reset/session hashes, failedLoginCount, or lockedUntil.

6.4 Endpoints

POST /api/v1/auth/register          { email, password, name }          → 201 UserPublic
POST /api/v1/auth/login             { email, password }                → 200 UserPublic
POST /api/v1/auth/logout            (auth or refresh cookie)           → 204
POST /api/v1/auth/logout-all        (auth)                             → 204
POST /api/v1/auth/refresh           (refresh cookie)                   → 200 UserPublic
POST /api/v1/auth/forgot-password   { email }                          → 200 { ok: true }
POST /api/v1/auth/reset-password    { token, password }                → 200 UserPublic

GET  /api/v1/users/me                                                  → 200 UserPublic
PATCH /api/v1/users/me              { name }                           → 200 UserPublic
POST /api/v1/users/me/password      { currentPassword, newPassword }   → 200 UserPublic

GET  /api/v1/work-orders          ?cursor&limit&status&priority&search  → 200 CursorPage<WorkOrderPublic>
POST /api/v1/work-orders          { title, description?, priority?, status? } → 201 WorkOrderPublic
GET  /api/v1/work-orders/:id                                                  → 200 WorkOrderPublic
PATCH /api/v1/work-orders/:id     { title?, description?, priority?, status?, version }
DELETE /api/v1/work-orders/:id    { version }  (JSON body)                   → 204

GET  /api/v1/admin/users            ?page&limit&role&search            → 200 OffsetPage<UserAdmin>
PATCH /api/v1/admin/users/:id/role  { role }                           → 200 UserAdmin
PATCH /api/v1/admin/users/:id/status { isActive }                      → 200 UserAdmin
GET  /api/v1/admin/work-orders     ?cursor&limit&status&priority&search  → 200 CursorPage<WorkOrderPublic>
GET  /api/v1/admin/metrics                                             → 200 { users, workOrders, uptimeSeconds }

GET  /health   → 200 { status: "ok" }
GET  /ready    → 200 { status: "ok" } | 503 { status: "degraded" }

7. Data Model

User

email            string   unique, lowercase, indexed
passwordHash     string
name             string
role             'admin' | 'user'
isActive         boolean
lastLoginAt      Date?
failedLoginCount number
lockedUntil      Date?
passwordReset    { tokenHash?: string, expiresAt?: Date }
createdAt        Date
updatedAt        Date

No deletedAt on User.

WorkOrder

title, description?, priority, status, owner, version, createdAt, updatedAt, deletedAt?

RefreshSession

userId, familyId, tokenHash, usedAt?, revokedAt?, expiresAt, createdAt, userAgent?, ip?

Indexes:

• User: unique { email: 1 }, { role: 1 }
• WorkOrder: { owner: 1, deletedAt: 1, createdAt: -1, _id: -1 }, { owner: 1, status: 1, deletedAt: 1 }, { owner: 1, priority: 1, deletedAt: 1 }
• RefreshSession: unique { tokenHash: 1 }, { familyId: 1 }, { userId: 1 }, TTL on expiresAt

8. Security

8.1 Passwords

bcrypt cost 12 via bcrypt.compare. Dummy hash for unknown emails. Cap length 72 in zod. Never log passwords or raw tokens.

8.2 Tokens

Access JWT: HS256, iss=mern-starter, aud=mern-starter-api, JWT_SECRET min 32 chars, reject placeholders (secret, changeme, replace-me). Rotation of JWT_SECRET invalidates access tokens; refresh sessions remain valid.

8.3 Cookies

Name	Path	Max-Age	Flags
access_token	/	900	httpOnly, SameSite=Lax, Secure in prod, host-only
refresh_token	/api/v1/auth	604800	same

COOKIE_SECRET signs cookie-parser cookies (integrity only). It is not authentication.

8.4 Rate limits

Scope	Key	Window	Max	Env
Global (except /health /ready)	IP	60s	300	RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX
/auth/login	IP	15m	10	RATE_LIMIT_LOGIN_MAX
/auth/forgot-password	IP + email	15m	3	RATE_LIMIT_FORGOT_MAX
/auth/register	IP	15m	10	(login max)

trust proxy hops from TRUST_PROXY_HOPS. In-process store (single instance).

8.5 CSRF / CORS / fetch

Same-origin only. CORS allowlist = CORS_ORIGIN (comma-separated), credentials: true. Frontend credentials: 'include'. CSRF tokens out of scope. Do not set cookie Domain. Do not enable urlencoded.

8.6 Injection

Recursive reject $/__proto__/constructor on body and query. Escape regex. HMAC cursors (never trust owner from cursor). Validate ObjectIds. Mongoose sanitizeFilter on user filters.

9. Project Structure

mern-starter-app/
├── package.json                 # workspaces: backend, frontend, packages/shared
├── package-lock.json
├── eslint.config.js
├── prettier.config.js
├── docker-compose.yml           # dev: mongo + api + vite
├── docker-compose.prod.yml      # mongo + api + nginx
├── nginx/nginx.conf
├── .github/workflows/ci.yml
├── .env.example
├── docs/SPEC.md
├── docs/GETTING_STARTED.md
├── docs/adr/
├── packages/shared/
├── backend/
│   ├── Dockerfile
│   ├── src/{config,models,repositories,services,controllers,routes,middleware,utils,schemas,app.ts,server.ts}
│   ├── src/scripts/seed.ts
│   └── tests/
└── frontend/
    ├── Dockerfile
    └── src/{api,components,features,hooks,lib,pages,main.tsx}

10. Environment

Validated at boot with zod; exit 1 on failure.

Key	Required	Notes
PORT	no	default 4000
NODE_ENV	no	development | test | production
MONGODB_URI	yes
JWT_SECRET	yes	min 32, not a placeholder
COOKIE_SECRET	yes	min 32
CORS_ORIGIN	yes	comma-separated origins
APP_URL	yes	public SPA origin (reset links)
SMTP_URL	no	unused in MVP mailer
TRUST_PROXY_HOPS	no	default 0
DEBUG_ERRORS	no	default false
LOG_LEVEL	no	default info
RATE_LIMIT_*	no	see §8.4
SEED_ADMIN_EMAIL	no	default admin@example.com
SEED_ADMIN_PASSWORD	no	default Admin1234
SEED_USER_EMAIL	no	default user@example.com
SEED_USER_PASSWORD	no	default User1234
VITE_APP_URL	frontend	same as APP_URL
VITE_API_URL	frontend	empty in dev (relative /api/v1); prod may set origin

No REFRESH_SECRET. Never commit real secrets.

11. Testing

CI Mongo: GitHub Actions services: mongo:7. Local: mongodb-memory-server when MONGODB_URI unset.

Mandatory backend integration

• AUTH-1/2 register+login cookies; duplicate email 409; inactive 401
• AUTH-4/6 refresh rotation; reuse revokes family; logout
• AUTH-7 forgot always 200; reset; token single-use
• AUTH-9/ADM-2 self-demote 403; last admin 403
• AUTH-11 five failures then lock (still 401)
• WO-2 owner isolation; WO-10 404 for others
• WO-6/9 stale version 409; omitted version 400
• WO-7 soft delete 204 then GET 404
• WO-4 regex escaped
• Envelope shape 400/401/403/404/409/429
• Extra fields on POST /work-orders do not persist

Frontend: auth forms (zod), protected route redirect, 409 conflict UI. Coverage thresholds in vitest config (backend 80%, frontend 60% of included files). Excludes: server.ts, Docker, generated.

12. CI/CD

.github/workflows/ci.yml on Node 20:

1. lint
2. typecheck
3. test + coverage (fail on threshold)
4. build
5. docker build (PRs and main)

13. Definition of Done

• §5 IDs implemented and covered by the test matrix.
• Lint, typecheck, tests pass with configured thresholds.
• README + GETTING_STARTED document setup, env, seed credentials.
• docker compose up --build serves the SPA and API on one browser origin.
• Seed produces admin + user.
• /health 200; register → login → create a work order works.
• No secrets committed.

14. Open Questions (resolved)

1. Mailer → log-only, redacted token. Real SMTP later.
2. Users → isActive only; no user hard/soft delete.
3. npm workspaces + Vite/nginx same-origin proxy.
4. React Query + auth context (useMe). No zustand.
5. i18n deferred; en-US.

Remaining: none for v1.

15. Risks

Risk	Sev	Mitigation
JWT secret leak	critical	min length, reject placeholders, 15m access TTL
Cookie CSRF on split origin	major	Same-origin only; no urlencoded; documented in ADR-0001
Register email enumeration	minor	Accepted (EMAIL_TAKEN); forgot-password does not leak
Account lockout DoS	major	IP limiter first; lockout hidden behind AUTH_GENERIC
Refresh reuse vs parallel refresh	major	Client single-flight + 10s grace
NoSQL injection	major	Recursive key reject + zod + ObjectId + HMAC cursor
In-process rate limits	minor	Single-instance assumption
Last-admin race	major	Count admins in service before write; DB role on each request
bcrypt vs load SLO	minor	SLO removed from DoD

16. Glossary

• Cursor — HMAC-protected token of { createdAt, id }.
• Family — lineage of rotated refresh sessions; reuse revokes the lineage.
• httpOnly cookie — not readable from JS.
• Soft delete — deletedAt set; hidden from default reads.
• Work order — a job owned by a technician, tracked pending → in_progress → done.
• Actor — { id, role } loaded from the database after JWT verify.

End of specification. v1.1 is the implementation contract.