documentation

README.md

@@ -130,7 +130,6 @@ Useful for showing the app to stakeholders without exposing live employee data.
 - 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
-- **Department filter**: pre-loaded dropdown of all departments for quick scoped views
 - Click any employee name to open their full profile modal
 - **📋 Audit Log** button — filterable, paginated view of all system write actions
 
@@ -138,9 +137,11 @@ Useful for showing the app to stakeholders without exposing live employee data.
 - 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
+- **Custom violation types**: add or edit user-defined types directly from the form (`+ Add Type` / `Edit Type` buttons); persisted to the database and merged into the dropdown alongside hardcoded types
 - **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
+- **Financial amount tracking**: dollar amount in question recorded for chargeback / receipt / custom financial violations; surfaces on the PDF for repayment records and is audit-logged on edit
 - **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
 - **Employee Acknowledgment section**: optional "received by employee" name and date fields; when filled, the PDF signature block shows the recorded acknowledgment instead of a blank signature line
@@ -214,23 +215,30 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/health` | Health check |
+| GET | `/api/health` | Health check (returns build SHA + timestamp) |
 | GET | `/api/employees` | List all employees (includes `notes`) |
+| GET | `/api/employees/:id` | Single employee record |
 | POST | `/api/employees` | Create or upsert employee |
 | PATCH | `/api/employees/:id` | Edit name, department, supervisor, or notes |
+| PATCH | `/api/employees/:id/notes` | Save employee notes only (shorthand) |
 | POST | `/api/employees/:id/merge` | Merge duplicate employee; reassigns all violations |
 | GET | `/api/employees/:id/score` | Get active CPAS score for employee |
 | GET | `/api/employees/:id/expiration` | Active violation roll-off timeline with days remaining |
-| PATCH | `/api/employees/:id/notes` | Save employee notes only (shorthand) |
+| GET | `/api/employees/:id/violation-counts` | 90-day non-negated counts grouped by violation type |
+| GET | `/api/employees/:id/violation-counts/alltime` | All-time non-negated counts + max points used per type |
 | GET | `/api/dashboard` | All employees with active points + violation counts |
-| POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`) |
+| POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`, `amount`) |
 | GET | `/api/violations/employee/:id` | Violation history with resolutions + amendment counts |
-| PATCH | `/api/violations/:id/negated` | Negate a violation (soft delete + resolution record) |
+| PATCH | `/api/violations/:id/negate` | Negate a violation (soft delete + resolution record) |
 | PATCH | `/api/violations/:id/restore` | Restore a negated violation |
 | PATCH | `/api/violations/:id/amend` | Amend non-scoring fields with field-level diff logging |
 | GET | `/api/violations/:id/amendments` | Get amendment history for a violation |
 | DELETE | `/api/violations/:id` | Hard delete a violation |
 | GET | `/api/violations/:id/pdf` | Download violation PDF |
+| GET | `/api/violation-types` | List custom violation types |
+| POST | `/api/violation-types` | Create a custom violation type |
+| PUT | `/api/violation-types/:id` | Update a custom violation type |
+| DELETE | `/api/violation-types/:id` | Delete a custom violation type (blocked if any violation references it) |
 | GET | `/api/audit` | Paginated audit log (filterable by `entity_type`, `entity_id`) |
 
 ---
@@ -258,24 +266,29 @@ cpas/
         ├── main.jsx
         ├── App.jsx                            # Root app + AppFooter (copyright, dev ticker, Gitea link)
         ├── data/
-        │   └── violations.js                 # All CPAS violation definitions + groups
+        │   ├── violations.js                  # All hardcoded CPAS violation definitions + groups
+        │   └── departments.js                 # DEPARTMENTS constant; single source of truth
         ├── hooks/
-        │   └── useEmployeeIntelligence.js    # Score + history hook
+        │   └── useEmployeeIntelligence.js     # Score + history hook
+        ├── styles/
+        │   └── mobile.css                     # Mobile breakpoint overrides only
         └── components/
-            ├── CpasBadge.jsx                 # Tier badge + color logic
-            ├── TierWarning.jsx               # Pre-submit tier crossing alert
-            ├── Dashboard.jsx                 # Company-wide leaderboard + audit log trigger
-            ├── ViolationForm.jsx             # Violation entry form + ack signature fields
-            ├── EmployeeModal.jsx             # Employee profile + history modal
-            ├── EditEmployeeModal.jsx         # Employee edit + merge duplicate
-            ├── AmendViolationModal.jsx       # Non-scoring field amendment + diff history
-            ├── AuditLog.jsx                  # Filterable audit log panel
-            ├── NegateModal.jsx               # Negate/resolve violation dialog
-            ├── ViolationHistory.jsx          # Violation list component
-            ├── ExpirationTimeline.jsx        # Per-violation 90-day roll-off countdown
-            ├── EmployeeNotes.jsx             # Inline notes editor with quick-add HR tags
-            ├── ToastProvider.jsx             # Global toast notification system + useToast hook
-            └── ReadmeModal.jsx              # In-app admin documentation panel
+            ├── CpasBadge.jsx                  # Tier badge + color logic (canonical TIERS, getTier)
+            ├── TierWarning.jsx                # Pre-submit tier crossing alert
+            ├── Dashboard.jsx                  # Company-wide leaderboard + audit log trigger
+            ├── DashboardMobile.jsx            # Mobile-optimized dashboard layout
+            ├── ViolationForm.jsx              # Violation entry form + ack signature + amount field
+            ├── ViolationTypeModal.jsx         # Create / edit / delete custom violation types
+            ├── EmployeeModal.jsx              # Employee profile + history modal
+            ├── EditEmployeeModal.jsx          # Employee edit + merge duplicate
+            ├── AmendViolationModal.jsx        # Non-scoring field amendment + diff history
+            ├── AuditLog.jsx                   # Filterable audit log panel
+            ├── NegateModal.jsx                # Negate/resolve violation dialog
+            ├── ViolationHistory.jsx           # Violation list component
+            ├── ExpirationTimeline.jsx         # Per-violation 90-day roll-off countdown
+            ├── EmployeeNotes.jsx              # Inline notes editor with quick-add HR tags
+            ├── ToastProvider.jsx              # Global toast notification system + useToast hook
+            └── ReadmeModal.jsx                # In-app admin documentation panel
 ```
 
 ---
@@ -284,10 +297,11 @@ cpas/
 
 Six tables + one view:
 
-- **`employees`** — id, name, department, supervisor, **notes**
-- **`violations`** — full incident record including `prior_active_points` snapshot at time of logging, `acknowledged_by` and `acknowledged_date` for employee acknowledgment
+- **`employees`** — id, name, department, supervisor, notes
+- **`violations`** — full incident record including `prior_active_points` snapshot, `acknowledged_by` / `acknowledged_date`, and `amount` (financial amount in question for chargeback/repayment)
 - **`violation_resolutions`** — resolution type, details, resolved_by (linked to violations)
 - **`violation_amendments`** — field-level diff log for violation edits; one row per changed field per amendment
+- **`violation_types`** — persisted custom violation type definitions added via the UI; `type_key` is prefixed `custom_` to prevent collisions with hardcoded keys
 - **`audit_log`** — append-only record of every write action (action, entity_type, entity_id, performed_by, details, timestamp)
 - **`active_cpas_scores`** (view) — sum of points for non-negated violations in rolling 90 days, grouped by employee
 
@@ -306,6 +320,7 @@ Point values, violation type, and incident date are **immutable** after submissi
 | `witness_name` | Witness on record |
 | `acknowledged_by` | Employee who acknowledged receipt |
 | `acknowledged_date` | Date of employee acknowledgment |
+| `amount` | Dollar amount in question (financial violations); typo-correctable for repayment records |
 
 ---
 
@@ -339,6 +354,8 @@ Point values, violation type, and incident date are **immutable** after submissi
 | 7 | Department dropdown | Pre-loaded select on the violation form replacing free-text department input; shared `DEPARTMENTS` constant |
 | 8 | Stakeholder demo page | Standalone `/demo` route with synthetic data; static HTML served before SPA catch-all; useful for non-live presentations |
 | 8 | App footer | Copyright (© Jason Stedwell), live dev ticker since first commit, Gitea repo icon+link |
+| 9 | Custom violation types | Persisted user-defined violation types created from the form; `+ Add Type` / `Edit Type` UI; merged into the dropdown alongside hardcoded types; delete blocked when in use |
+| 9 | Financial amount tracking | `amount` field on financial violations (chargeback, receipt negligence, custom types with the field enabled); stored on `violations`, rendered prominently on the PDF, amendable with audit-logged diffs |
 
 ---