Work Order Desk

A web application for field service teams. A technician logs a job, tracks it, and closes it. A dispatcher sees every job on the team. The application is built with MongoDB, Express, React, and Node.js.

A work order is a job to do in the field. Each work order has a title, a description, a status, and a priority. The status is pending, in_progress, or done. The priority is low, medium, or high.

Roles

• A technician is a user. A technician owns their work orders.
• A dispatcher is an admin. An admin manages users and sees every work order.
• A visitor can register, log in, and reset a password.

Auth and security

• The app uses cookies for login. The cookies are httpOnly. JavaScript cannot read them.
• The app rotates refresh tokens. It detects reused tokens and revokes the token family.
• The app stores passwords with bcrypt at cost 12.
• The API uses a closed error catalog.
• Every request has a request ID.

Tech stack

Layer	Technology
Runtime	Node.js 20 LTS
Language	TypeScript 5.x
API	Express 4.x
Database	MongoDB 7.x with Mongoose 8.x
Frontend	React 18 with Vite 5 and Tailwind CSS 3
Server state	TanStack Query 5
Validation	zod 3
Tests	Vitest, Supertest, Testing Library
Containers	Docker and Compose
Tooling	ESLint 9, Prettier 3, npm workspaces

AI features

AI is opt-in and off by default: without AI_ENABLED=true (plus AI_BASE_URL and AI_API_KEY) the AI surfaces below are inert and the app behaves exactly as before.

• Copilot (M1): an assistant embedded in the SPA (open with Cmd+K). It answers questions about your own work orders and drafts or updates them on your behalf. Writes are staged: the app shows a server-rendered before/after diff and nothing changes until you approve (human-in-the-loop). Approvals expire after AI_APPROVAL_TTL_MS. Streams over SSE; all tool calls are validated server-side against a per-role allowlist.
• Autonomous triage agent (M2): a background worker watches newly created work orders and produces a summary + priority suggestion. In suggest mode it writes a TriageSuggestion (flagged items appear in the dispatcher's attention list); in auto-apply mode it can apply the suggested priority directly. It runs under a bounded policy (step caps, per-agent/global spend ledgers, working hours, kill switch).
• Admin: /app/admin/agents exposes the triage policy, run history, and a kill switch; everything is audited. Runs and costs are recorded (AgentRun, AgentToolCall, AgentSpend); AI_API_KEY never leaves the backend.

Run with Docker

1. Copy the environment template. Run cp .env.example .env.
2. Start the stack. Run docker compose up --build.
3. Open http://localhost:5173.
4. Log in as admin@example.com with Admin1234.

You can also log in as user@example.com with User1234.

Run without Docker

1. Copy the environment template. Run cp .env.example .env.
2. Install packages. Run npm install.
3. Create the seed users. Run npm run seed.
4. Add demo data. Run npm run seed:demo.
5. Start the app. Run npm run dev.

The backend runs on port 4000. The frontend runs on port 5173.

The seed command creates an admin user and a user. The demo command adds technicians and work orders. The demo data makes the app look lived in.

To try the Copilot after npm run seed:demo, the triage worker is a separate process: run npm run worker in a second terminal (or docker compose up, which runs it as a container). The worker needs no extra setup — it reads the same .env as the backend.

Checks

Run these commands before you push a change.

npm run lint
npm run typecheck
npm test
npm run build

CI runs these checks on every push. CI also runs coverage gates. npm run worker is a separate long-running process (the autonomous triage agent); it is not part of the checks. Start it locally with npm run worker (or npm run worker:dev for watch mode).

Production notes

• The demo accounts are public and shown on the login page. Change the admin password before you use the app in public.
• Render's free tier sleeps after about 15 minutes without traffic. The first request then takes 30 to 60 seconds to start. Use a paid plan or a warm-up ping for production.
• Password reset emails use Resend. Set RESEND_API_KEY and verify a sender domain before real users sign up.
• Work-order search uses a case-insensitive regex. It is correct but does a full scan. It is fine at starter scale.
• The triage worker must be deployed alongside the API (both compose files ship a worker service). Run exactly one API instance: approvals are held in the in-process approval registry, so scaling the API horizontally would split pending approvals across processes.

Project structure

• backend: the Express API. It uses a layered architecture.
• backend/src/agent: the agentic AI runtime (runtime loop, tool registry, OpenAI-compatible provider, injection policy).
• backend/src/worker.ts: the autonomous triage worker — a separate process (outbox poller + policy enforcement).
• frontend: the React application.
• frontend/src/features/copilot: the Copilot UI (dockable panel, SSE stream hook, approval modal).
• frontend/src/features/admin: the admin agent settings and run-history pages.
• packages/shared: the shared zod schemas and TypeScript types.
• SPEC.md: the technical specification.
• AGENTIC-AI-SPEC.md: the agentic AI conversion specification (copilot + autonomous triage).

Environment variables

Copy .env.example to .env. The .env file is ignored by git. Never commit real secrets. Generate secrets with openssl rand -hex 32.

The app reads the .env file from the backend workspace or from the repo root. Docker Compose reads the root .env file.

The AI keys (AI_ENABLED, AI_BASE_URL, AI_API_KEY, model/budget/worker tunables) are all documented in .env.example under the "Agentic AI" section. AI is off by default; see AI features.