# Connecticut Elderly Services PCA Training Platform - Project Summary

## Version: v0.1 (in active development)

## What Was Built

A Node.js + Express web application for PCA (Personal Care Attendant) certification training based on the Connecticut DSS PCA Certification Test. Runs on cPanel with Phusion Passenger. Admin auth uses MySQL; learner data uses SQLite.

## File Inventory

### Core Application (3 files)
- **app.js** - Main Express server; session setup (connect-sqlite3), routing, data/ dir auto-creation
- **package.json** - Node.js dependencies
- **.env.example** - Environment variables template

### Database Layer (3 files)
- **lib/db.js** - SQLite database (data/training.db) — learner/module/exam data only
  - Promise-based async API; auto-initializes all tables on first run
  - Seed data for demo agencies (DEMO123, TEST456)
- **lib/mysqldb.js** - MySQL/MariaDB — admin authentication only
  - Admin user lookup, scrypt password verification, password change, user creation
  - Used exclusively by routes/admin.js; credentials set via cPanel environment variables
- **lib/auth.js** - Shared crypto helpers: scrypt hash + timing-safe verify (used by mysqldb.js)

### Training Content (3 files)
- **lib/modules.js** (29 KB) - All 12 training modules with complete lesson content and 5-question quizzes
- **lib/examContent.js** (18 KB) - 19-section final certification exam with 100+ questions
- **lib/certificate.js** (2.8 KB) - PDF certificate generation using PDFKit

### Supporting Libraries (2 files)
- **lib/email.js** - Email notifications for certificate delivery (optional)
- **lib/version.js** - BUILD_ID constant; visit /admin/version to confirm live code after deploy

### Scripts (1 file)
- **scripts/create-admin.js** - CLI tool to create/reset admin accounts via MySQL (requires terminal)

### Routes/API (3 files)
- **routes/learner.js** - Module viewing, quiz submission, learner flow
- **routes/exam.js** - Exam delivery, scoring, results, certificate generation
- **routes/admin.js** - Admin authentication (MySQL only), CSRF protection, rate limiting, dashboard

### Views/Templates (14 files)
- **views/layout.ejs** / **views/index.ejs** / **views/start.ejs** - Landing, home, name entry
- **views/modules/module.ejs** / **views/modules/complete.ejs** - Lesson + quiz, completion
- **views/exam.ejs** / **views/result.ejs** / **views/error.ejs** - Exam, results, error
- **views/admin/login.ejs** - Admin login (username + password, no default)
- **views/admin/dashboard.ejs** - Admin panel: stats, learner roster, agency management
- **views/admin/change-password.ejs** - Admin password change form (CSRF protected)
- **views/admin/bootstrap.ejs** - First-admin setup form (token + CSRF protected)

### Styling & Scripts (2 files)
- **public/css/style.css** (37 KB) - Professional, responsive CSS with:
  - Navy (#1a3a5c) and gold (#f0a500) color scheme
  - Google Fonts Inter typography
  - Mobile-first responsive design
  - Card-based layout
  - Progress bar animations
  - Print-friendly certificate styles

- **public/js/main.js** (1.8 KB) - Client-side utilities and event handling

### Documentation (2 files)
- **SETUP.md** (7.4 KB) - Complete non-technical setup and deployment guide
- **PROJECT_SUMMARY.md** (This file) - Project overview and inventory

## Directory Structure

```
ces-training/
├── app.js                           [Main application]
├── package.json                     [Dependencies]
├── .env.example                     [Configuration template]
├── SETUP.md                         [Setup guide]
├── PROJECT_SUMMARY.md               [This file]
│
├── data/                            [Auto-created on first run]
│   ├── training.db                  [SQLite — learner/module/exam data]
│   └── sessions.db                  [SQLite — session store (connect-sqlite3)]
│
├── public/                          [Static files]
│   ├── css/
│   │   └── style.css                [37 KB polished CSS]
│   ├── js/
│   │   └── main.js                  [JavaScript utilities]
│   └── certificates/                [Generated PDFs - auto-created]
│
├── lib/                             [Application logic]
│   ├── db.js                        [SQLite — learner/module data]
│   ├── mysqldb.js                   [MySQL — admin auth only]
│   ├── auth.js                      [Shared crypto helpers]
│   ├── version.js                   [BUILD_ID for deploy verification]
│   ├── modules.js                   [12 training modules]
│   ├── examContent.js               [19 exam sections]
│   ├── certificate.js               [PDF generation]
│   └── email.js                     [Email notifications]
│
├── scripts/
│   └── create-admin.js              [CLI: create/reset MySQL admin users]
│
├── routes/                          [API endpoints]
│   ├── learner.js                   [Module routes]
│   ├── exam.js                      [Exam routes]
│   └── admin.js                     [Admin routes]
│
└── views/                           [EJS templates]
    ├── layout.ejs                   [Base template]
    ├── index.ejs                    [Home page]
    ├── start.ejs                    [Entry form]
    ├── exam.ejs                     [Final exam]
    ├── result.ejs                   [Results]
    ├── error.ejs                    [Error page]
    ├── modules/
    │   ├── module.ejs               [Lesson + quiz]
    │   └── complete.ejs             [Completion]
    └── admin/
        ├── login.ejs                [Admin login]
        ├── dashboard.ejs            [Admin panel]
        ├── change-password.ejs      [Password change form]
        └── bootstrap.ejs            [First-admin setup]
```

## Features Implemented

### Learner Flow
1. Landing page with module overview
2. Name & agency code entry (pre-seeded: DEMO123, TEST456)
3. 12 sequential training modules:
   - Teach-first lesson content
   - 5-question knowledge check quiz
   - Must score 70%+ to pass
   - Progress bar showing completion
4. Module sidebar navigation
5. Final certification exam:
   - 19 sections covering all DSS PCA test material
   - Server-side scoring (answers never sent to client)
   - Section-by-section pass/fail evaluation
   - Must score 70%+ in ALL sections to pass
6. Results page showing:
   - Pass/fail status
   - Section-by-section scores
   - Certificate download link (if passed)
7. PDF certificate generation with professional formatting
8. Certificate storage and retrieval

### Admin Features
- Secured login at /admin/login — username + hashed password stored in MySQL
- No default password. First account created via /admin/bootstrap or phpMyAdmin SQL
- Dashboard showing:
  - Total learners count
  - Completed trainings count
  - Passed certifications count
  - Pass rate percentage
- Learner roster table with:
  - Name, agency, dates, status
  - Clickable certificate download links
  - Color-coded status (In Progress, Passed, Failed)
- Agency management:
  - View existing agencies
  - Add new agency codes dynamically

### Database
- **SQLite3** (data/training.db) — learner data only:
  - **agencies** - Organization codes
  - **learners** - Learner records with scores
  - **module_progress** - Module completion tracking
  - Auto-initialization on first run; seed data included (DEMO123, TEST456)
- **MySQL/MariaDB** (cPanel) — admin auth only:
  - **admin_users** - Admin accounts with scrypt-hashed passwords
  - Managed via phpMyAdmin; credentials set in cPanel environment variables

### Security
- Admin authentication via MySQL — no default password, no plaintext fallback
- CSRF synchronizer tokens on all admin state-changing POST routes
- Rate limiting on `/admin/login` (10 req/15 min) and `/admin/bootstrap` (5 req/15 min)
- Sessions stored in `data/sessions.db` via connect-sqlite3 — survive restarts, safe for multi-process cPanel
- Server-side exam scoring (answers never sent to client)
- scrypt password hashing with per-user random salts and timing-safe comparison

## Training Content

### 12 Complete Training Modules
1. Emergency Response (11 points covered)
2. Universal Precautions (10 points)
3. Communication (10 points)
4. Monitoring Condition Changes (10 points)
5. Positioning (6 points)
6. Safe Lifting (10 points)
7. Safe Transfers (5 points)
8. Medication Safety (9 points)
9. Professional Boundaries (10 points)
10. Brain Injury, Dementia & Behavior (14 points)
11. Reporting Abuse & Neglect (5 points)
12. Personal Care - Bathing, Hair & Mouth Care (20 points)

**Total**: 12 modules × 5 questions each = 60 knowledge check questions

### 19 Final Exam Sections
- **Sections**: 19 comprehensive sections
- **Total Questions**: 100+ questions
- **Scoring**: Section-based (must pass ALL)
- **Pass Threshold**: 70% in each section

Sections include:
- Preventing Emergency Situations (16 Q)
- Universal Precautions (10 Q)
- Communication (10 Q)
- Monitoring Condition Changes (10 Q)
- Positioning (11 Q)
- Lifting (10 Q)
- Transfers (5 Q)
- Medication (9 Q)
- Caregiver Boundaries (10 Q)
- Acquired Brain Injury (14 Q)
- Reporting Abuse & Neglect (5 Q)
- Bathing (5 Q)
- Bathing with Dementia (5 Q)
- Bed Bath (5 Q)
- Washing Hair (5 Q)
- Washing Hair in Bed (5 Q)
- Mouth Care (5 Q)
- Mouth Care with Dementia (5 Q)
- Dressing (5 Q)

## Technology Stack

- **Backend**: Node.js + Express.js (runs on cPanel/Phusion Passenger)
- **Learner data**: SQLite3 (`sqlite3` npm package) — `data/training.db`
- **Admin auth**: MySQL/MariaDB (`mysql2` npm package) — cPanel-hosted database
- **Session store**: `connect-sqlite3` — `data/sessions.db` (survives restarts, safe for cPanel)
- **Templating**: EJS (Embedded JavaScript)
- **PDF Generation**: PDFKit
- **Email**: Nodemailer (optional)
- **Security**: CSRF tokens (synchronizer pattern), rate limiting (`express-rate-limit`), scrypt password hashing
- **Styling**: Pure CSS (no build tools needed)

## Design Highlights

### Color Scheme
- Primary: Deep Navy (#1a3a5c)
- Secondary: Warm Gold/Amber (#f0a500)
- Success: Green (#28a745)
- Danger: Red (#dc3545)
- Background: Light Gray (#f8f9fa)

### Typography
- Font: Inter (Google Fonts)
- Clean, professional, highly readable
- Responsive font sizes

### Layout
- Card-based components
- Progress bars with animations
- Mobile-first responsive design
- Print-friendly certificate page
- Subtle shadows and depth

### UX Features
- Module navigation sidebar
- Progress percentage display
- Color-coded status badges
- Inline feedback (pass/fail immediate results)
- Learner name display in header
- Clean forms with validation

## Deployment Ready

The application is configured for:
- **cPanel**: Uses app.js as startup file
- **Docker**: Can be containerized easily
- **Cloud**: AWS, Heroku, DigitalOcean, etc.
- **Local**: npm install && npm start

## Setup Instructions

1. Copy all files to desired location
2. Copy .env.example to .env and configure
3. Run: npm install
4. Run: npm start
5. Visit http://localhost:3000

See SETUP.md for detailed instructions.

## File Statistics

- **JavaScript files**: 14 (app.js + 8 lib + 3 routes + 1 script + main.js)
- **EJS templates**: 14
- **CSS**: 1 (37 KB)
- **Documentation**: SETUP.md, README.md, PROJECT_SUMMARY.md

## v0.1 Checklist

- [x] Node.js + Express on cPanel/Phusion Passenger
- [x] SQLite (learner/module/exam data) + MySQL (admin auth)
- [x] SQLite-backed session store (survives restarts)
- [x] 12 complete training modules with full lesson content
- [x] 5-question quizzes per module (70% pass threshold)
- [x] 19-section final exam with 100+ questions
- [x] Server-side exam scoring
- [x] PDF certificate generation
- [x] Admin dashboard: stats, learner roster, agency management
- [x] Admin login via MySQL — no default password
- [x] CSRF protection + rate limiting on admin routes
- [x] Browser-based first-admin setup (/admin/bootstrap)
- [x] Professional, mobile-responsive CSS design
- [x] Error handling and session hardening
- [x] Email notifications (optional)

## Notes

- All content is based on actual Connecticut DSS PCA Certification Test requirements
- Learner data uses SQLite3 (no extra server needed); admin auth requires a MySQL/MariaDB database
- Certificates are generated as PDF files and stored locally in `public/certificates/`
- There is no default admin password — you must create the first account via /admin/bootstrap or the CLI script
- Email functionality is optional (app runs fine without SMTP configured)
- Sessions persist in `data/sessions.db` — deleting this file logs everyone out

## Support

See SETUP.md for troubleshooting and customization guidance.

---

**Project Status**: v0.1 — core learner and admin flows working; additional features planned
**Last Updated**: April 4, 2026
