From a6447970accac67c62da054aee0bd8a209bcf161 Mon Sep 17 00:00:00 2001 From: jason Date: Fri, 6 Mar 2026 23:18:28 -0600 Subject: [PATCH] docs: update README to reflect current codebase (phases 1-4 complete) --- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 110 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a448dde..ad78091 100755 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # CPAS Violation Tracker -Single-container Dockerized web app for CPAS violation documentation. -Built with React + Vite (frontend), Node.js + Express (backend), SQLite (database). +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 — happens inside Docker. +Everything else — Node.js, npm, React build, Chromium for PDF — happens inside Docker. --- @@ -41,18 +43,88 @@ 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__.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-violation-tracker/ -├── Dockerfile # Multi-stage: builds React + runs Express +cpas/ +├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium ├── .dockerignore -├── package.json # Backend (Express) deps -├── server.js # API + static file server +├── package.json # Backend (Express) deps +├── server.js # API + static file server ├── db/ -│ ├── schema.sql # Tables + 90-day score view -│ └── database.js # SQLite connection -└── client/ # React frontend (Vite) +│ ├── 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 @@ -60,14 +132,36 @@ cpas-violation-tracker/ ├── main.jsx ├── App.jsx ├── data/ - │ └── violations.js # All CPAS violation definitions + │ └── violations.js # All CPAS violation definitions + groups + ├── hooks/ + │ └── useEmployeeIntelligence.js # Score + history hook └── components/ - └── ViolationForm.jsx + ├── 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 + - [x] Phase 1 — Container scaffold, SQLite schema, base React form -- [ ] Phase 2 — Employee history, prior violation highlighting -- [ ] Phase 3 — Puppeteer PDF generation -- [ ] Phase 4 — Dashboard, CPAS scores, tier warnings -- [ ] Phase 5 — Recidivist point auto-suggest +- [x] Phase 2 — Employee history, prior violation highlighting, recidivist point auto-suggest +- [x] Phase 3 — Puppeteer PDF generation +- [x] Phase 4 — Dashboard, CPAS scores, tier warnings, at-risk badges +- [ ] Phase 5 — Recidivist point auto-suggest refinements / additional reporting