CPAS Violation Tracker

Single-container Dockerized web app for CPAS violation documentation and workforce standing management. Built with React + Vite (frontend), Node.js + Express (backend), SQLite (database), and Puppeteer (PDF generation).

---

The only requirement on your machine: Docker Desktop

Everything else — Node.js, npm, React build, Chromium for PDF — happens inside Docker.

---

Quickstart (Local)

# 1. Build the image (installs all deps + compiles React inside Docker)
docker build -t cpas-tracker .

# 2. Run it
docker run -d --name cpas-tracker \
  -p 3001:3001 \
  -v cpas-data:/data \
  cpas-tracker

# 3. Open
# http://localhost:3001

Export for Unraid

docker save cpas-tracker | gzip > cpas-tracker.tar.gz

Then follow README_UNRAID_INSTALL.md.

Update After Code Changes

docker build -t cpas-tracker .
docker stop cpas-tracker && docker rm cpas-tracker
docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker

---

Features

Company Dashboard

• Live table of all employees sorted by active CPAS points (highest risk first)
• Summary stat cards: total employees, elite standing (0 pts), with active points, at-risk count, highest active score
• At-risk badge: flags employees within 2 points of the next tier escalation
• Search/filter by name, department, or supervisor
• Click any employee name to open their full profile modal

Violation Form

• Select existing employee or enter new employee by name
• Employee intelligence: shows current CPAS standing badge and 90-day violation count before submitting
• Violation type dropdown grouped by category; shows prior 90-day counts inline
• Recidivist auto-escalation: if an employee has prior violations of the same type, points slider auto-sets to maximum per policy
• Repeat offense badge with prior count displayed
• Context-sensitive fields (time, minutes late, amount, location, description) shown only when relevant to violation type
• Tier crossing warning (TierWarning component): previews what tier the new points would push the employee into before submission
• Point slider for discretionary adjustments within the violation's min/max range
• One-click PDF download immediately after submission

Employee Profile Modal

• Full violation history with resolution status
• Negate / restore individual violations (soft delete with resolution type + notes)
• Hard delete option for data entry errors
• PDF download for any historical violation record

CPAS Tier System

Points	Tier	Label
0–4	0–1	Elite Standing
5–9	1	Realignment
10–14	2	Administrative Lockdown
15–19	3	Verification
20–24	4	Risk Mitigation
25–29	5	Final Decision
30+	6	Separation

Scores are computed over a rolling 90-day window (negated violations excluded).

PDF Generation

• Puppeteer + system Chromium (bundled in Docker image)
• Generated on-demand per violation via GET /api/violations/:id/pdf
• Filename: CPAS_<EmployeeName>_<IncidentDate>.pdf
• PDF captures prior active points at the time of the incident (snapshot stored on insert)

---

API Reference

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/employees	List all employees
POST	/api/employees	Create or upsert employee
GET	/api/employees/:id/score	Get active CPAS score for employee
GET	/api/dashboard	All employees with active points + violation counts
POST	/api/violations	Log a new violation
GET	/api/violations/employee/:id	Get violation history for employee (with resolutions)
PATCH	/api/violations/:id/negate	Negate a violation (soft delete + resolution record)
PATCH	/api/violations/:id/restore	Restore a negated violation
DELETE	/api/violations/:id	Hard delete a violation
GET	/api/violations/:id/pdf	Download violation PDF

---

Project Structure

cpas/
├── Dockerfile                     # Multi-stage: builds React + runs Express w/ Chromium
├── .dockerignore
├── package.json                   # Backend (Express) deps
├── server.js                      # API + static file server
├── db/
│   ├── schema.sql                 # Tables + 90-day active score view
│   └── database.js                # SQLite connection (better-sqlite3)
├── pdf/
│   └── generator.js               # Puppeteer PDF generation
└── client/                        # React frontend (Vite)
    ├── package.json
    ├── vite.config.js
    ├── index.html
    └── src/
        ├── main.jsx
        ├── App.jsx
        ├── data/
        │   └── violations.js      # All CPAS violation definitions + groups
        ├── hooks/
        │   └── useEmployeeIntelligence.js  # Score + history hook
        └── components/
            ├── CpasBadge.jsx      # Tier badge + color logic
            ├── TierWarning.jsx    # Pre-submit tier crossing alert
            ├── Dashboard.jsx      # Company-wide leaderboard
            ├── ViolationForm.jsx  # Violation entry form
            ├── EmployeeModal.jsx  # Employee profile + history modal
            ├── NegateModal.jsx    # Negate/resolve violation dialog
            └── ViolationHistory.jsx  # Violation list component

---

Database Schema

Three tables + one view:

• employees — id, name, department, supervisor
• violations — full incident record including prior_active_points snapshot at time of logging
• violation_resolutions — resolution type, details, resolved_by (linked to violations)
• active_cpas_scores (view) — sum of points for non-negated violations in rolling 90 days, grouped by employee

---

Phases

• Phase 1 — Container scaffold, SQLite schema, base React form
• Phase 2 — Employee history, prior violation highlighting, recidivist point auto-suggest
• Phase 3 — Puppeteer PDF generation
• Phase 4 — Dashboard, CPAS scores, tier warnings, at-risk badges
• Phase 5 — Recidivist point auto-suggest refinements / additional reporting