mirror of
https://github.com/vee1e/workorder-desk.git
synced 2026-09-01 17:57:11 +00:00
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# Work Order Desk
|
|
|
|
Work Order Desk is 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 |
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## Project structure
|
|
|
|
- `backend`: the Express API. It uses a layered architecture.
|
|
- `frontend`: the React application.
|
|
- `packages/shared`: the shared zod schemas and TypeScript types.
|
|
- `SPEC.md`: the technical specification.
|
|
|
|
## 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.
|