SafePath Training — Implementation Overview
Summary
SafePath Training is a standalone-first, HazCom-extensible training management module. This implementation plan is broken into focused documents, each covering a specific phase or subsystem.
Architecture
tellus-ehs-hazcom-service/
├── app/
│ ├── db/models/
│ │ └── safepath.py # All SafePath SQLAlchemy models
│ ├── schemas/
│ │ └── safepath/
│ │ ├── __init__.py
│ │ ├── course.py # Course & lesson schemas
│ │ ├── quiz.py # Quiz & question schemas
│ │ ├── assignment.py # Assignment schemas
│ │ ├── result.py # Result & certificate schemas
│ │ ├── certification.py # Certification tracking schemas
│ │ ├── classroom.py # In-person training schemas
│ │ ├── dashboard.py # Dashboard & reporting schemas
│ │ ├── matrix.py # Training matrix schemas
│ │ ├── hazcom_integration.py # HazCom integration schemas (Phase 2A)
│ │ └── automation.py # Automation schemas (Phase 2B)
│ ├── services/
│ │ └── safepath/
│ │ ├── __init__.py
│ │ ├── course_service.py # Course CRUD & versioning
│ │ ├── assignment_service.py # Assignment engine
│ │ ├── delivery_service.py # Training delivery & progress
│ │ ├── quiz_service.py # Quiz scoring & evaluation
│ │ ├── certification_service.py # Certification tracking
│ │ ├── certificate_generator.py # PDF certificate generation
│ │ ├── classroom_service.py # In-person training records
│ │ ├── dashboard_service.py # Dashboard aggregations
│ │ ├── matrix_service.py # Training matrix generation
│ │ ├── report_service.py # Compliance reports & exports
│ │ ├── hazcom_integration_service.py # HazCom integration (Phase 2A)
│ │ ├── auto_assignment_engine.py # Auto-assignment rules (Phase 2B)
│ │ ├── notification_service.py # Notifications (Phase 2B)
│ │ └── scheduler.py # Scheduled tasks (Phase 2B)
│ └── api/v1/
│ └── safepath/
│ ├── __init__.py
│ ├── courses.py # Course & lesson endpoints
│ ├── assignments.py # Assignment endpoints
│ ├── results.py # Result & certificate endpoints
│ ├── certifications.py # Certification tracking endpoints
│ ├── classroom.py # In-person training endpoints
│ ├── dashboard.py # Dashboard endpoints
│ ├── matrix.py # Training matrix endpoints
│ ├── hazcom_integration.py # HazCom integration endpoints (Phase 2A)
│ └── automation.py # Automation endpoints (Phase 2B)
tellus-ehs-hazcom-ui/
├── src/
│ ├── pages/safepath/
│ │ ├── index.tsx # SafePath dashboard
│ │ ├── courses/
│ │ │ ├── index.tsx # Course list
│ │ │ ├── create.tsx # Course creation wizard
│ │ │ └── [id].tsx # Course detail/edit
│ │ ├── assignments/
│ │ │ ├── index.tsx # Assignment list
│ │ │ └── [id].tsx # Assignment detail (learner view)
│ │ ├── certifications/
│ │ │ └── index.tsx # Certification tracker
│ │ ├── matrix/
│ │ │ └── index.tsx # Training matrix view
│ │ ├── reports/
│ │ │ └── index.tsx # Reports & exports
│ │ └── automation/ # Phase 2B
│ │ ├── index.tsx # Automation hub
│ │ ├── rules.tsx # Auto-assignment rules manager
│ │ └── notifications.tsx # Notification preferences
│ ├── types/safepath.ts # TypeScript interfaces
│ └── services/safepath-api.ts # API client methods
Current State
| Component | Status | Notes |
|---|---|---|
| SafePath database tables | ✅ Complete | 12 safepath_ tables in production |
| SafePath models | ✅ Complete | app/db/models/safepath.py |
| SafePath schemas | ✅ Complete | app/schemas/safepath/ (8 files) |
| SafePath services | ✅ Complete | app/services/safepath/ (11 services) |
| SafePath API routes | ✅ Complete | app/api/v1/safepath/ (7 route files, 45 endpoints) |
| SafePath UI pages | ✅ Complete | src/pages/safepath/ (40+ files) |
| PDF certificate generation | ✅ Complete | ReportLab-based certificate_generator.py |
| ChemIQ Integration (Phase 2A) | ❌ Not built | Auto-generated HazCom courses, chemical-change retraining |
| Standalone Automation (Phase 2B) | ❌ Not built | Auto-assignment rules, notifications, cert alerts |
| Alembic migration infrastructure | ✅ Exists | tellus-ehs-hazcom-service/alembic/ |
| Base model pattern | ✅ Exists | app.db.session.Base |
| Auth & user context | ✅ Exists | get_user_context dependency |
| Company/site/role models | ✅ Exists | Used for assignment targeting |
| Module entitlement checking | ✅ Exists | Can gate SafePath features by tier |
Implementation Documents
Phase 1: Core Training Platform (Standalone) — ✅ Complete
| Document | Phase | Covers |
|---|---|---|
| Database Schema & Migrations | 1A | All 12 safepath_ tables, Alembic migration, seed data |
| Course Management | 1B | Course CRUD, lessons, quizzes, versioning — backend + frontend |
| Assignment & Training Delivery | 1C | Assignment engine, training delivery, quiz scoring, completion records |
| Certification Tracking | 1D | Certification types, expiration tracking, external certs, dashboard |
| Dashboard, Reports & Training Matrix | 1E | Dashboard views, compliance reports, training matrix, exports |
| Onboarding Adaptations | 1F | Context-aware onboarding, quickstart wizard, starter templates, capabilities |
Phase 2: HazCom Extension & Automation — 🔲 Not Started
| Document | Phase | Covers |
|---|---|---|
| ChemIQ Integration | 2A | Auto-generated HazCom courses, chemical-change retraining, SDS-linked content, GHS pictogram training |
| Standalone Automation | 2B | Auto-assignment rules engine, notification & reminder automation, certification expiration alerts |
Implementation Order
Phase 1: Core Training Platform (COMPLETE)
═══════════════════════════════════════════
Phase 1A: Database Schema ✅
│
├── Phase 1B: Course Management ✅
│ │
│ └── Phase 1C: Assignment & Delivery ✅
│ │
│ ├── Phase 1D: Certification Tracking ✅
│ │
│ └── Phase 1E: Dashboard & Reports ✅
│
├── Phase 1F: Onboarding Adaptations ✅
│
└── (All phases depend on 1A)
Phase 2: HazCom Extension & Automation (NOT STARTED)
═══════════════════════════════════════════════════════
Phase 1 (all) ──┐
│
├── Phase 2A: ChemIQ Integration
│ (requires ChemIQ + HazCom Plan modules)
│ - Auto-generated HazCom courses from plan + SDS data
│ - Chemical-change retraining triggers
│ - GHS pictogram training
│
└── Phase 2B: Standalone Automation
(standalone, no ChemIQ dependency)
- Auto-assignment rules engine
- Notification & reminder automation
- Certification expiration alerts
Phase 1 is complete. Phase 2A and 2B can be built in parallel since they are independent — 2A integrates with ChemIQ/HazCom Plan modules while 2B adds standalone automation features. Both depend on Phase 1 being complete.
Key Conventions
Naming
- Database tables:
safepath_prefix (e.g.,safepath_courses,safepath_assignments) - Models file:
app/db/models/safepath.py(single file for all SafePath models) - Schemas folder:
app/schemas/safepath/(one file per domain) - Services folder:
app/services/safepath/(one file per domain) - API folder:
app/api/v1/safepath/(one file per domain)
Patterns to Follow
- SQLAlchemy models inherit from
app.db.session.Base - UUID primary keys with
uuid4default company_idFK on every tenant-scoped table- Pydantic v2 schemas with
model_config = ConfigDict(from_attributes=True) - FastAPI dependency injection via
Depends(get_user_context)andDepends(get_db) - Paginated list responses with
items,total,page,page_size,total_pages - Error responses:
{"success": false, "message": "...", "error": "..."}
Feature Flags
All SafePath features are gated by the SAFEPATH module entitlement. Tier-specific features (auto-assignment, AI explainer, multi-company) are additionally gated by plan-level entitlements.