diff --git a/README.md b/README.md index 9e3f23f..891be75 100755 --- a/README.md +++ b/README.md @@ -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 | ---