jason/cpas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'docs: update README with Phase 8 features, expanded roadmap with effort ratings' (#37) from feature/readme-update into master

Browse Source 
Reviewed-on: #37
This commit was merged in pull request #37.
This commit is contained in:
jason
2026-03-08 00:33:39 -06:00
parent 5f0ae959ed 7326ffec6e
commit dc45cb7d83
1 changed files with 85 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@@ -3,6 +3,8 @@
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).
> © Jason Stedwell · [git.alwisp.com/jason/cpas](https://git.alwisp.com/jason/cpas)
---
## The only requirement on your machine: Docker Desktop
@@ -113,6 +115,14 @@ Access the app at `http://10.2.0.14:3001` (or whatever static IP you assigned).
---
## Stakeholder Demo
A standalone demo page with synthetic data is available at `/demo` (e.g. `http://localhost:3001/demo`).
It is served as a static route before the SPA catch-all and requires no authentication.
Useful for showing the app to stakeholders without exposing live employee data.
---
## Features
### Company Dashboard
@@ -120,8 +130,9 @@ Access the app at `http://10.2.0.14:3001` (or whatever static IP you assigned).
- 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
- **📋 Audit Log** button — filterable, paginated view of all system write actions
### Violation Form
- Select existing employee or enter new employee by name
@@ -170,6 +181,11 @@ Access the app at `http://10.2.0.14:3001` (or whatever static IP you assigned).
- Slide-in animation; stacks up to 5 notifications simultaneously
- Consistent dark theme styling matching the rest of the UI
### App Footer
- **© Jason Stedwell** copyright with auto-advancing year
- **Live dev ticker**: real-time elapsed counter since first commit (`2026-03-06`), ticking every second in `Xd HHh MMm SSs` format with a pulsing green dot
- **Gitea repo link** with icon — links directly to `git.alwisp.com/jason/cpas`
### CPAS Tier System
| Points | Tier | Label |
@@ -209,7 +225,7 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude
| GET | `/api/dashboard` | All employees with active points + violation counts |
| POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`) |
| GET | `/api/violations/employee/:id` | Violation history with resolutions + amendment counts |
| PATCH | `/api/violations/:id/negate` | Negate a violation (soft delete + resolution record) |
| PATCH | `/api/violations/:id/negated` | 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 |
@@ -223,42 +239,43 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude
```
cpas/
├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium
├── 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 active score view
│ ├── schema.sql # Tables + 90-day active score view
│ └── database.js # SQLite connection (better-sqlite3) + auto-migrations
├── pdf/
│ ├── generator.js # Puppeteer PDF generation
│ └── template.js # HTML template (loads logo from disk, ack signature rendering)
├── demo/ # Static stakeholder demo page (served at /demo)
└── client/ # React frontend (Vite)
├── package.json
├── vite.config.js
├── index.html
└── src/
├── main.jsx
├── App.jsx
├── App.jsx # Root app + AppFooter (copyright, dev ticker, Gitea link)
├── data/
│ └── violations.js # All CPAS violation definitions + groups
│ └── violations.js # All CPAS violation definitions + groups
├── hooks/
│ └── useEmployeeIntelligence.js # Score + history hook
│ └── useEmployeeIntelligence.js # Score + history hook
└── 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
├── 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
```
---
@@ -319,32 +336,65 @@ Point values, violation type, and incident date are **immutable** after submissi
| 6 | In-app documentation | Admin usage guide and feature map accessible from the navbar |
| 7 | Acknowledgment signature field | "Received by employee" name + date on the violation form; renders on the PDF replacing blank signature lines with recorded acknowledgment |
| 7 | Toast notification system | Global success/error/warning/info notifications for all user actions; auto-dismiss with progress bar; consistent dark theme |
| 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 |
---
### 📋 Proposed
Effort ratings: 🟢 Low · 🟡 Medium · 🔴 High
#### Quick Wins (High value, low effort)
| Feature | Effort | Description |
|---------|--------|-------------|
| Column sort on dashboard | 🟢 | Click `Tier`, `Active Points`, or `Department` headers to sort in-place; one `useState` + comparator, no API changes |
| Department filter on dashboard | 🟢 | Multi-select dropdown to scope the employee table by department; `DEPARTMENTS` constant already exists |
| Keyboard shortcut: New Violation | 🟢 | `N` key triggers tab switch to the violation form; ~5 lines of code |
| CSV export of dashboard | 🟢 | Client-side Blob download of the current filtered employee view; no backend changes needed |
#### 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
- **Department heat map** — grid view showing violation density and average CPAS score by department; helps supervisors identify team-level risk
- **CSV / Excel export** — bulk export of violations or dashboard data for external reporting or payroll integration
| Feature | Effort | Description |
|---------|--------|-------------|
| Violation trend chart | 🟡 | Line/bar chart of violations per day/week/month, filterable by department or supervisor; useful for identifying systemic patterns |
| Department heat map | 🟡 | Grid view showing violation density and average CPAS score by department; helps supervisors identify team-level risk |
| Violation sparklines per employee | 🟡 | Tiny inline bar chart of points over the last 6 months in the employee modal |
| CSV / Excel bulk export | 🟡 | Full export of violations or dashboard data for external reporting or payroll integration |
#### Employee Management
- **Supervisor view** — scoped dashboard showing only the employees under a given supervisor, useful for multi-supervisor environments
| Feature | Effort | Description |
|---------|--------|-------------|
| Supervisor scoped view | 🟡 | Dashboard filtered to a supervisor's direct reports, accessible via URL param (`?supervisor=Name`); no schema changes required |
| Employee photo / avatar | 🟢 | Optional avatar upload stored alongside the employee record; shown in the profile modal and dashboard row |
#### Violation Workflow
- **Draft / pending violations** — save a violation as draft before finalizing, useful when incidents need review before being officially logged
- **Bulk violation import** — CSV import for migrating historical records from paper logs or a prior system
| Feature | Effort | Description |
|---------|--------|-------------|
| Draft / pending violations | 🟡 | Save a violation as draft before finalizing; useful when incidents need review before being officially logged |
| Bulk violation import | 🔴 | CSV import for migrating historical records from paper logs or a prior system |
| Violation templates | 🟢 | Pre-fill the form with a saved violation type + common details for frequently logged incidents |
#### Notifications & Escalation
- **Tier escalation alerts** — email or in-app notification when an employee crosses into Tier 2+ so the relevant supervisor is automatically informed
- **Scheduled summary digest** — weekly email to supervisors listing their employees' current standings and any approaching tier thresholds
- **At-risk threshold configuration** — make the "at-risk" warning threshold (currently hardcoded at 2 pts) configurable per deployment
| Feature | Effort | Description |
|---------|--------|-------------|
| Scheduled expiration digest | 🟡 | Weekly or daily email listing violations rolling off in the next 7 days; `nodemailer` + cron on the Node server |
| Tier escalation alerts | 🟡 | Email or in-app notification when an employee crosses into Tier 2+ so the relevant supervisor is automatically informed |
| At-risk threshold config | 🟢 | Make the "at-risk" warning threshold (currently hardcoded at 2 pts) configurable per deployment via an env var |
| version.json / build badge | 🟢 | Inject git SHA + build timestamp into a static file during `docker build`; surfaced in the footer and `/api/health` |
#### Infrastructure & Ops
- **Multi-user auth** — simple login with role-based access (admin, supervisor, read-only); currently the app has no auth and is assumed to run on a trusted internal network
- **Automated DB backup** — cron job or Docker health hook to snapshot `/data/cpas.db` to a mounted backup volume or remote location on a schedule
- **Dark/light theme toggle** — the UI is currently dark-only; a toggle would improve usability in bright environments
| Feature | Effort | Description |
|---------|--------|-------------|
| Multi-user auth | 🔴 | Simple login with role-based access (admin, supervisor, read-only); currently the app runs on a trusted internal network with no auth |
| Automated DB backup | 🟡 | Cron job or Docker health hook to snapshot `/data/cpas.db` to a mounted backup volume or remote location on a schedule |
| Dark/light theme toggle | 🟡 | The UI is currently dark-only; a toggle would improve usability in bright environments |
---