- **Merge Duplicate** tab — reassign all violations from a duplicate record and delete it
- **Merge Duplicate** tab — reassign all violations from a duplicate record and delete it
- **Amend** button per active violation — edit non-scoring fields (location, notes, witness, etc.) with a full field-level diff history
- **Amend** button per active violation — edit non-scoring fields (location, notes, witness, etc.) with a full field-level diff history
- Negate / restore individual violations (soft delete with resolution type + notes)
- Negate / restore individual violations (soft delete with resolution type + notes)
- Hard delete option for data entry errors
- Hard delete option for data entry errors
- PDF download for any historical violation record
- PDF download for any historical violation record
- **Notes & Flags** — free-text notes (e.g. "on PIP", "union member") with quick-add tag buttons; visible in the profile modal without affecting scoring
- **Point Expiration Timeline** — shows when each active violation rolls off the 90-day window, with a progress bar, days-remaining countdown, and projected tier-drop indicators
### Audit Log
### Audit Log
- Append-only log of every write action: employee created/edited/merged, violation logged/amended/negated/restored/deleted
- Append-only log of every write action: employee created/edited/merged, violation logged/amended/negated/restored/deleted
| 5 | Audit log | Append-only log of all system writes; filterable panel in the dashboard |
| 5 | Audit log | Append-only log of all system writes; filterable panel in the dashboard |
| 6 | Employee notes / flags | Free-text notes on employee record with quick-add HR tags; does not affect scoring |
| 6 | Point expiration timeline | Per-violation roll-off countdown with tier-drop projections |
| 6 | In-app documentation | Admin usage guide and feature map accessible from the navbar |
---
---
### 📋 In Progress
### 📋 Proposed
#### Reporting & Visibility
- **Expiration timeline** — per-employee view showing which active violations roll off the 90-day window and when; lets supervisors anticipate tier drops before they happen
- **Employee notes / flags** — free-text notes attached to an employee record (e.g. "on PIP", "union member") visible in the profile modal without affecting scoring
---
### 💡 Proposed
#### Reporting & Analytics
#### Reporting & Analytics
- **Violation trends chart** — line/bar chart of violations per day/week/month, filterable by department or supervisor; useful for identifying systemic patterns vs. individual incidents
- **Violation trends chart** — line/bar chart of violations per day/week/month, filterable by department or supervisor; useful for identifying systemic patterns vs. individual incidents
Internal tool for CPAS violation documentation, workforce standing management, and audit compliance. All data is stored locally in the Docker container volume — there is no external dependency.
// Embedded at build time — no extra fetch needed.
constREADME_MD=`# 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).
---
---
## Quickstart (Local)
## How CPAS Scoring Works
\`\`\`bash
Every violation carries a **point value** set at the time of submission. Points count toward an employee's score only within a **rolling 90-day window** — once a violation is older than 90 days it automatically drops off and the score recalculates.
# 1. Build the image
docker build -t cpas-tracker .
# 2. Run it
Negated (voided) violations are excluded from scoring immediately. Hard-deleted violations are removed from the record entirely.
3. Choose a violation type. The dropdown is grouped by category and shows prior 90-day counts inline for each type.
- **\`violation_amendments\`** — field-level diff log per amendment
4. If the employee has a prior violation of the same type, the **recidivist auto-escalation** rule triggers — the points slider jumps to the maximum allowed for that violation type.
- **\`audit_log\`** — append-only record of every write action
5. The **tier crossing warning** previews what tier the submission would land the employee in. Review before submitting.
- **\`active_cpas_scores\`** (view) — rolling 90-day score per employee
6. Adjust points using the slider if discretionary reduction is warranted (within the violation's allowed min/max range).
7. Submit. A **PDF download link** appears immediately — download it for the employee's file.
---
---
## Amendable Fields
### Employee Profile Modal
The following violation fields can be edited after submission. Points, type, and incident date are **immutable**.
Click any name on the dashboard to open their profile.
| Field | Notes |
#### Overview section
|-------|-------|
Shows current tier badge, active points, and 90-day violation count.
| \`incident_time\` | Time of day the incident occurred |
| \`location\` | Where the incident took place |
#### Notes & Flags
| \`details\` | Narrative description |
Free-text field for HR context (e.g. "On PIP", "Union member", "Pending investigation", "FMLA"). Quick-add tag buttons pre-fill common statuses. Notes are visible to anyone who opens the profile but **do not affect CPAS scoring**. Edit inline; saves on blur.
| \`submitted_by\` | Supervisor who submitted |
| \`witness_name\` | Witness on record |
#### Point Expiration Timeline
Visible when the employee has active points. Shows each active violation as a progress bar indicating how far through its 90-day window it is, days remaining until roll-off, and a **tier-drop indicator** for violations whose expiration would move the employee down a tier.
#### Violation History
Full record of all submissions — active, negated, and resolved.
- **Amend** — edit non-scoring fields (location, details, witness, submitted-by, incident time) on any active violation. Every change is logged as a field-level diff (old → new) with timestamp. Points, type, and incident date are immutable.
- **Negate** — soft-delete a violation with a resolution type and notes. The record is preserved in history; the points are immediately removed from the score. Fully reversible via **Restore**.
- **Hard delete** — permanent removal. Use only for genuine data entry errors.
- **PDF** — download the formal violation document for any historical record.
#### Edit Employee
Update name, department, or supervisor. Changes are logged to the audit trail.
#### Merge Duplicate
If the same employee exists under two names, use Merge to reassign all violations from the duplicate to the canonical record. The duplicate is then deleted. This cannot be undone.
---
---
## Docker Quick Reference
### Audit Log
\`\`\`bash
Accessible from the dashboard toolbar (🔍 button). Append-only log of every write action in the system.
# Build
docker build -t cpas-tracker .
# Run
- Filter by entity type: **employee** or **violation**
docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker
docker save cpas-tracker | gzip > cpas-tracker.tar.gz
# View logs
### Violation Amendment
docker logs -f cpas-tracker
\`\`\`
Amendments allow corrections to a violation's non-scoring fields without deleting and re-submitting, which would disrupt the audit trail and the prior-points snapshot.
**Amendable fields:** incident time, location, details, submitted-by, witness name.
**Immutable fields:** violation type, incident date, point value.
Each amendment stores a before/after diff for every changed field. Amendment history is accessible from the violation card in the employee's history.
---
## Immutability Rules — Quick Reference
| Action | Allowed? | Notes |
|--------|----------|-------|
| Edit violation type | No | Immutable after submission |
| Edit incident date | No | Immutable after submission |
| Edit point value | No | Immutable after submission |
- Employee profile modal — full history, negate/restore, hard delete
- Employee edit and duplicate merge
- Violation amendment with field-level diff log
- Audit log — filterable, paginated, append-only
- Employee notes and flags with quick-add HR tags
- Point expiration timeline with tier-drop projections
- In-app admin guide (this panel)
---
### 🔜 Near-term
These are well-scoped additions that fit the current architecture without major changes.
- **Acknowledgment signature field** — "received by employee" name + date on the violation form; prints on the PDF in place of the blank signature line. Addresses the most common field workflow gap.
- **CSV export** — one endpoint returning violations or dashboard data as a downloadable CSV for payroll or external reporting.
- **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments without requiring full auth.
---
### 📋 Planned
Larger features that require more design work or infrastructure.
- **Violation trends chart** — line/bar chart of violations over time, filterable by department or supervisor. Useful for identifying systemic patterns vs. isolated incidents. Recharts is already available in the frontend bundle.
- **Department heat map** — grid showing violation density and average CPAS score per department. Helps identify team-level risk early.
- **Draft / pending violations** — save a violation as a draft before it's officially logged. Useful when incidents need supervisor review or HR sign-off before they count toward the score.
- **At-risk threshold configuration** — make the 2-point at-risk warning threshold configurable per deployment rather than hardcoded.
---
### 🔭 Future Considerations
These require meaningful infrastructure additions and should be evaluated against actual operational need before committing.
- **Multi-user auth** — role-based login (admin, supervisor, read-only). Currently the app assumes a trusted internal network with no authentication layer.
- **Tier escalation alerts** — email or in-app notification when an employee crosses into Tier 2+, automatically routed to their supervisor.
- **Scheduled digest** — weekly email summary to supervisors showing their employees' current standings and any approaching thresholds.
- **Automated DB backup** — scheduled snapshot of `/data/cpas.db` to a mounted backup volume or remote destination.
- **Bulk CSV import** — migrate historical violation records from paper logs or a prior system.
- **Dark/light theme toggle** — UI is currently dark-only.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
jason