ReqFlow Backend

REST API for Internal Request & Approval Management

Validate it, route it to the right approvers, record it, track it to completion.

Overview · Key Features · Tech Stack · System Workflow · API Overview · Getting Started · Testing · Project Structure · Project Context

Overview

ReqFlow Backend is the server-side component of ReqFlow, a web-based system for managing organizational requests, structured approvals, fulfillment tracking, and operational reporting. It owns the business logic, data persistence, authentication, authorization, and API services consumed by the ReqFlow frontend. Every record is scoped to an organization.

Key Features

• 🔐 Authentication & Authorization: cookie-based sessions with server-side revocation, Argon2id password hashing, and five roles (EMPLOYEE, MANAGER, FINANCE, DIRECTOR, ADMIN). No public sign-up: Admins provision accounts.
• 📝 Request Management: purchase, equipment, reimbursement, leave, and general requests with a draft → in review → approved / rejected / revision / cancelled lifecycle.
• ✅ Multi-Level Approval: policy-driven Manager → Finance → Director chains chosen from request type and amount, with approve, reject, and request-revision decisions; resubmission starts a new cycle and keeps history.
• 🚚 Fulfillment Tracking: after approval, an accountable assignee starts and completes the work with a recorded note. Approval and fulfillment are separate lifecycles. Admins assign, reassign, and cancel.
• 🔔 Notifications: in-app notifications for requesters, approvers, and fulfillment assignees.
• 🧾 Audit Logging: append-only audit trail written in the same transaction as the event it records.
• 📊 Reporting & Export: dashboard summary, requests-over-time, request and workflow-duration reports, with CSV, PDF, and Excel export.
• 👥 Users & Departments: Admin-managed users, roles, activation, and departments.
• 💬 Comments & Attachments: request discussion and file attachments (type allowlist, size cap).

Tech Stack

Area	Technology
Runtime / language	Node.js ≥ 20, TypeScript (ESM)
Framework	Express 5, helmet, cors, cookie-parser, express-rate-limit, multer
Database / ORM	PostgreSQL, Prisma 7 with @prisma/adapter-pg
Security	argon2, opaque server-side sessions
Validation	Zod 4
Reporting	pdfkit, exceljs, internal CSV writer
Testing / quality	Vitest, Supertest, ESLint, Prettier

System Workflow

1. An employee creates a draft request and submits it.
2. The backend validates the input and authorization, resolves the approvers, and fails the submission if a required approver does not exist.
3. The request moves through the approval chain:
   • PURCHASE under Rp 5,000,000: Manager. From Rp 5,000,000: Manager → Finance. From Rp 20,000,000: Manager → Finance → Director.
   • REIMBURSEMENT: always Manager → Finance.
   • EQUIPMENT, LEAVE, GENERAL: Manager only.
4. Each approver approves, rejects, or asks for a revision. A rejection ends the request; a revision lets the owner edit and resubmit. The owner can also cancel a draft or withdraw one in review, and an Admin can reassign a stuck step.
5. An approved request (except leave) opens a fulfillment: it is assigned (Finance for purchases and reimbursements, an Admin-chosen assignee for equipment and general requests), started, and completed with a note. Completion is an internal record, not an external verification.
6. Every step writes audit records and notifications and is reflected in dashboards and reports.

API Overview

Full reference: docs/API.md.

Module	Responsibility	Example
Authentication	Login, session, password change	POST /auth/login
Requests	Create, update, submit, cancel, list, detail	POST /requests/:id/submit
Approvals	Inbox, decisions, reassignment	POST /approvals/:id/approve
Fulfillment	Task list, start, complete, assign, cancel	POST /requests/:id/fulfillment/complete
Comments & Attachments	Discussion and files on a request	POST /requests/:id/comments
Users & Departments	Admin user and department management	POST /users
Audit & Notifications	Request audit timeline, user notifications	GET /requests/:id/audit-log
Dashboard & Reports	Summary, charts data, reports, exports	GET /dashboard/summary
Health	Liveness and database readiness	GET /health · GET /ready

Getting Started

Prerequisites: Node.js ≥ 20, npm, and a running PostgreSQL instance.

git clone <repository-url> && cd reqFlow-backend
npm install
cp .env.example .env          # then set DATABASE_URL and review the other values
npm run prisma:generate
npm run prisma:deploy         # apply migrations
npm run dev                   # http://localhost:3000

Create the first account (required, since there is no public registration) from a trusted terminal:

npm run create:admin

Optional development data: npm run db:seed (minimal users) or npm run seed:demo (a 32-request demo organization, development databases only). See docs/DEVELOPMENT.md for the demo commands and their safeguards.

Variable	Default	Notes
DATABASE_URL	none (required)	PostgreSQL connection string
PORT	3000
NODE_ENV	development	development, test, or production
CORS_ORIGIN	http://localhost:5173	Must be a real origin in production
UPLOAD_DIR	./storage/uploads	Local attachment storage
MAX_ATTACHMENT_SIZE_MB	10

Production build: npm run build && npm start.

Testing

npm test        # vitest run
npm run lint    # eslint
npm run build   # tsc type-check + compile

Tests use Vitest and Supertest against a real PostgreSQL database named reqflow_test (the setup refuses to run against any other database because it deletes data between cases). They cover authentication and sessions, role and resource authorization, the request lifecycle and state transitions, approval routing and decisions, fulfillment, reporting and exports, user management, and the demo seed. No CI workflow is configured in this repository.

Project Structure

src/
  config/        Environment validation, Prisma client, logger
  routes/        Route tables and auth/role guards
  controllers/   HTTP handlers (parse input with Zod)
  services/      Business logic, transactions, authorization rules
  middlewares/   Auth, roles, rate limit, upload, error handler
  schemas/       Zod request schemas
  utils/         Password, session, CSV/PDF/XLSX, rich-text helpers
prisma/          Schema, migrations, seed and demo scripts
tests/           Vitest unit and integration suites
docs/            API, architecture, database, development guides

More detail: Architecture · Database · Development.

Project Context

ReqFlow Backend was built to demonstrate practical backend engineering: REST API design with Express, relational data modeling with Prisma and PostgreSQL, role-based and resource-level authorization, transactional approval and fulfillment workflows with an audit trail, and a layered, tested codebase. It is a portfolio project, not a deployed product.