ContractorOS

Unified contractor lifecycle platform — onboarding, invoicing, classification risk monitoring, compliance documents, and offboarding.

Built for operations leads, finance teams, and HR admins at companies managing 20–200 contractors.

Live Demo · Getting Started · Architecture

---

---

The Problem

Contractor management is duct-taped across 3–5 disconnected tools. Onboarding checklists live in spreadsheets, invoices pile up in email, W-9s go missing until the 1099 filing deadline, and 83% of former contractors still have system access after leaving. Meanwhile, misclassification penalties run $10,000–$25,000 per worker in high-enforcement states, and no existing tool monitors risk continuously.

ContractorOS replaces that patchwork with a single platform that handles the full contractor lifecycle — from the first invite to the final access revocation.

Key Features

• Onboarding Pipeline — Kanban board tracking contractors through invite, tax forms, contract signing, and bank details. Bulk invites and automated step progression.

• Classification Risk Monitor — Continuous scoring against three legal tests (IRS common-law, DOL economic realities, California ABC). Weighted risk aggregation with drill-down into individual factors. Daily automated re-assessment via CRON.

• Invoice Workflow Engine — Full state machine: Draft → Submitted → Under Review → Approved → Scheduled → Paid. Multi-level approval routing, duplicate detection, and complete status history.

• Compliance Document Vault — Centralized storage for W-9s, W-8BENs, contracts, NDAs, and insurance certificates. Version tracking, expiration alerts, and 1099 readiness reporting.

• Offboarding Automation — Auto-generated 9-item checklist covering access revocation, equipment return, final invoicing, and knowledge transfer. Post-termination invoice blocking.

• Contractor Self-Service Portal — Contractors submit invoices, upload documents, track payment status, and manage their profile through a dedicated portal.

• Audit Log — Immutable append-only log of every state-changing operation, with old/new value capture and filterable query interface.

• Notifications — Real-time notification system with 11 event types triggered across invoices, classification alerts, offboarding, and document expiry.

Tech Stack

Layer	Technology
Frontend	Next.js 15 (App Router), React 19, Tailwind CSS
Backend	NestJS 11, raw SQL via pg driver (no ORM)
Database	PostgreSQL 16
Validation	Zod schemas (shared between frontend and backend)
Testing	Jest (362 unit tests), Cypress (26 E2E tests), Storybook (45+ stories)
CI/CD	GitHub Actions (lint, type-check, unit, integration, E2E)
Build	Turborepo, pnpm workspaces

Architecture

apps/
  api/          NestJS backend — REST API, auth, business logic, raw SQL
  web/          Next.js frontend — admin dashboard, contractor portal

packages/
  shared/       TypeScript types, Zod schemas, constants, state machines

The backend uses raw parameterized SQL queries — no ORMs. Every ID is a UUID, every timestamp is TIMESTAMPTZ, and every state transition is enforced by explicit state machines in the shared package.

Database Schema (21 tables)

Table	Purpose
organizations	Multi-tenant root
users	All authenticated users (admin, manager, contractor)
contractors	Core entity with 7-status lifecycle
contractor_status_history	Temporal status tracking
onboarding_steps	4-stage onboarding pipeline
engagements	Scopes of work with hourly/fixed rates
time_entries	Hours logged against engagements
invoices	8-status invoice lifecycle
invoice_line_items	Individual billable items
invoice_status_history	Invoice transition audit trail
approval_steps	Multi-level approval chain
tax_documents	6 document types with version tracking
classification_assessments	Risk scores across 3 legal tests
classification_factors	Raw engagement data for scoring
offboarding_workflows	5-status offboarding process
offboarding_checklist_items	9-item auto-generated checklist
equipment	Company-issued device tracking
audit_events	Immutable append-only audit log
notifications	11 notification types
refresh_tokens	JWT refresh token rotation
mv_classification_risk_summary	Materialized view for dashboard

API Routes (59 endpoints)

All routes are prefixed with /api/v1.

Auth — Login, logout, refresh, invite accept, password reset (7 endpoints)

Contractors — CRUD, bulk invite, onboarding pipeline, tax summary (9 endpoints)

Engagements — CRUD with status transitions (5 endpoints)

Time Entries — CRUD with engagement validation (5 endpoints)

Invoices — Full lifecycle with state machine actions: submit, approve, reject, dispute, schedule, mark-paid, cancel (12 endpoints)

Documents — Upload, download, soft-delete, compliance report, 1099 readiness (7 endpoints)

Classification — Risk assessment, history, manual re-score, dashboard, factor management (6 endpoints)

Offboarding — Initiate, checklist management, workflow updates (5 endpoints)

Audit Log — Filterable query with entity type, action, and date range (1 endpoint)

Notifications — List, mark read, mark all read (3 endpoints)

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10.28+
• PostgreSQL 16

Installation

# Clone the repository
git clone https://github.com/jeffgicharu/contractor-os.git
cd contractor-os

# Install dependencies
pnpm install

Environment Setup

# API environment
cp apps/api/.env.example apps/api/.env

# Web environment
cp apps/web/.env.example apps/web/.env

The defaults work for local development. Key variables:

# apps/api/.env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/contractor_os
JWT_SECRET=your-jwt-secret-change-in-production
PORT=3001
CORS_ORIGIN=http://localhost:3000

# apps/web/.env
NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1

Database Setup

# Create the database
createdb contractor_os

# Run migrations (9 migration files covering all tables + indexes)
pnpm --filter @contractor-os/api migrate:up

# Seed with demo data (55+ contractors, 130+ invoices, 340+ time entries,
# a coherent ~85% document-compliance distribution, and a ~5-month audit trail)
pnpm --filter @contractor-os/api seed

# Restore the stable demo/E2E accounts (idempotent — the full seed above
# rebuilds every org, so always re-run this immediately after it)
pnpm --filter @contractor-os/api seed:demo-accounts

Run

# Start both API and frontend in development mode
pnpm dev

The API runs on http://localhost:3001 and the frontend on http://localhost:3000.

Demo Credentials

Role	Email	Password
Admin	admin@acme-corp.com	Password1
Contractor	john.smith@example.com	Password1

Testing

# Unit tests
pnpm test

# Integration tests (Testcontainers Postgres)
pnpm --filter @contractor-os/api test:integration

# E2E tests (Cypress)
pnpm --filter @contractor-os/web cypress:run

# Component stories
pnpm --filter @contractor-os/web storybook

Quality Engineering

ContractorOS is actively closing quality gaps documented in AUDIT.md. The current state of every quality metric — coverage, mutation, performance, security — lives in QUALITY_DASHBOARD.md.

Per-discipline documentation:

• TEST_STRATEGY.md — pyramid, per-package coverage targets, CI gates, non-functional budgets
• QA_BEST_PRACTICES.md — code-review checklist, BDD test naming, flaky-test policy, mock-vs-real policy
• SECURITY_TESTING.md — threat model, SAST + dependency + container + DAST + custom suite, OWASP Top 10 mapping
• AI_TESTING_PLAYBOOK.md — how AI assistance is used (and where it's not) when authoring tests in this repo

Open quality issues — including the gaps the strategy targets close — are listed in QUALITY_DASHBOARD.md § Open quality issues.

Project Structure

apps/api/src/
  auth/               JWT auth with refresh token rotation
  contractors/        Contractor CRUD + onboarding pipeline
  engagements/        Engagement management + status transitions
  time-entries/       Time tracking with engagement validation
  invoices/           Invoice lifecycle + approval routing
  documents/          Document vault + compliance reporting
  classification/     Risk scoring (IRS, DOL, ABC tests) + CRON
  offboarding/        Offboarding workflows + checklist generation
  audit/              Immutable audit log with diff capture
  notifications/      Event-driven notification system
  database/
    migrations/       9 versioned migrations (node-pg-migrate)
    seeds/            Demo data generator

apps/web/src/
  app/
    (auth)/           Login, invite accept pages
    (admin)/          Admin dashboard, all management pages
    (portal)/         Contractor self-service portal
  components/
    layout/           Sidebar, header, portal navigation
    ui/               Shared primitives (button, input, modal, badge)
    invoices/         Invoice-specific components
    contractors/      Contractor-specific components
    offboarding/      Offboarding-specific components
  hooks/              use-auth, use-api, use-contractors, etc.
  lib/                API client, utilities

packages/shared/src/
  types/              TypeScript interfaces for all entities
  schemas/            Zod validation schemas
  constants/          State machines, enums, status transitions