# WPA (Work Place Assessment) System - Comprehensive Guide

## Overview

The Work Place Assessment (WPA) system is a comprehensive assessment management platform within the diving education application. It consists of two main components:
1. **WPA Builder** - Content development tools for creating assessments
2. **DMT Assessment Viewer** - Assessment delivery and evaluation interface

## System Architecture

### 1. WPA Builder (Content Development Side)

**Location**: `lib/screens/content_dev/wpa/`

#### Main Components:
- **WPACreationScreen** - Main assessment creation interface
- **WPAManagementScreen** - Assessment management and overview
- **WPA Components** - Reusable UI components for building assessments

#### Key Features:
- **Multi-tab Interface**: Metadata, Criteria, POI Assignment, Preview
- **Assessment Types**: `practical_skills`, `competency_based`, `knowledge_based`
- **Import/Export**: JSON-based assessment import and export
- **POI Integration**: Assign assessments to specific Points of Interest
- **Real-time Preview**: Live preview of assessment structure

### 2. DMT Assessment Viewer (Student/Assessor Side)

**Location**: `lib/screens/dmt_assessment_screen.dart` and `lib/screens/dmt_json_viewer_screen.dart`

#### Key Features:
- **Assessment Overview**: List all available DMT assessments
- **Dual View Modes**: 
  - `formatted` - Read-only view of assessment details
  - `assessment` - Interactive assessment completion interface
- **Assessor Login**: Secure access for qualified assessors
- **Progressive Assessment**: Step-by-step criteria evaluation
- **Real-time Scoring**: Dynamic score calculation and feedback

## Data Structure

### WPA Assessment Model

```dart
class WPAAssessment {
  final String id;                    // Unique identifier
  final String code;                  // Assessment code (e.g., "WPA-SAFETY-001")
  final String description;           // Human-readable description
  final String type;                  // Assessment type
  final bool active;                  // Whether assessment is active
  final int criteriaCount;            // Number of assessment criteria
  final DateTime lastModified;        // Last modification timestamp
  final String createdBy;            // Creator information
  final String? instruction;         // Assessment instructions
  final String? norm;                // Assessment standards/norms
  final int numberOfRetests;         // Allowed retests (default: 3)
  final bool autoActivate;           // Auto-activation setting
  final List<WPACriteria>? criteria; // Assessment criteria list
  final List<WPAPOIAssignment>? assignedPOIs; // POI assignments
}
```

### WPA Criteria Model

```dart
class WPACriteria {
  final String description;          // What needs to be assessed
  final int? weight;                 // Scoring weight
  final int? sortCode;               // Display order
  final List<String> whatToLookFor;  // Assessment guidelines
}
```

### POI Assignment Model

```dart
class WPAPOIAssignment {
  final String poiId;                // POI identifier
  final String poiName;              // POI display name
  final String poiType;              // POI category
  final String category;             // Assignment category
  final bool isRequired;             // Whether POI is mandatory
  final int? unlockLevel;            // Required level to access
  final String? prerequisite;        // Prerequisites
}
```

## JSON Data Format

### Current DMT Assessment Structure

**Location**: `assets/data/dmt/`

```json
{
  "metadata": {
    "assessment_id": "ASS_20181003074903_54a9f0d9-e181-4f70-a",
    "assessment_code": "DMT Wounds",
    "total_score_items": 40,
    "source_file": "dmt-wounds.json"
  },
  "assessment": {
    "description": "Practical Skills Assessment - 10 point WOUND assessment",
    "assessment_type": "wpa",
    "norm": "7.5",
    "active": false,
    "auto_activate": true,
    "number_of_retests": "1",
    "instruction": "Complete assessment instructions..."
  },
  "score_items": {
    "related": [
      {
        "description": "Complete accurate documentation, sign and dated.",
        "weight": "1",
        "sort_code": "1",
        "what_to_look_for": [
          "Check for proper documentation",
          "Verify signature and date"
        ]
      }
    ]
  }
}
```

### WPA Builder Generated Structure

```json
{
  "metadata": {
    "assessment_id": "WPA_001",
    "assessment_code": "WPA-SAFETY-001",
    "total_score_items": 5,
    "source_file": "wpa-safety-001.json"
  },
  "assessment": {
    "description": "Workplace Safety Assessment",
    "assessment_type": "practical_skills",
    "norm": "OSHA Safety Standards",
    "active": true,
    "auto_activate": false,
    "number_of_retests": 3,
    "instruction": "Assessment instructions..."
  },
  "score_items": {
    "related": [
      {
        "description": "Identify workplace hazards",
        "weight": 2,
        "sort_code": 1,
        "what_to_look_for": [
          "Check for proper visual scanning",
          "Identify slip, trip, fall hazards"
        ]
      }
    ]
  },
  "poi_assignments": [
    {
      "poi_id": "training_center_01",
      "poi_name": "Main Training Center",
      "poi_type": "Training Facility",
      "category": "training",
      "is_required": true,
      "unlock_level": 1
    }
  ]
}
```

## Data Flow

### 1. Assessment Creation Flow

```
WPA Builder → JSON Generation → (Currently) Local Storage
                              → (Future) Firebase Storage
```

1. **Content Developer** uses WPA Creation Screen
2. **Metadata Entry**: Basic assessment information
3. **Criteria Definition**: Define what will be assessed
4. **POI Assignment**: Link assessment to map locations
5. **Preview & Export**: Generate JSON structure
6. **Storage**: Save to Firebase (planned implementation)

### 2. Assessment Delivery Flow

```
Assessment List → Assessment Selection → Assessment Execution → Results
```

1. **DMT Assessment Screen** loads available assessments
2. **Assessment Selection** from summary list
3. **JSON Viewer Screen** handles assessment execution
4. **Assessor Login** for qualified evaluation
5. **Progressive Assessment** through criteria
6. **Score Calculation** and result generation

## Current Data Sources

### DMT Assessments
- **Source**: Static JSON files in `assets/data/dmt/`
- **Summary**: `_summary.json` contains overview of all assessments
- **Individual Files**: Each assessment has its own JSON file
- **Total Assessments**: 9 DMT assessments currently available

### WPA Builder Assessments
- **Source**: In-memory sample data (not persisted)
- **Demo Data**: Hardcoded examples for demonstration
- **Export**: Generates JSON but not saved permanently

## Key Integration Points

### 1. POI System Integration
- **POI Assignment**: Link assessments to specific map locations
- **Categories**: training, assessment, emergency, research, etc.
- **Access Control**: Level-based and prerequisite requirements
- **Map Navigation**: Direct access from CPD Island Map

### 2. Assessment Evaluation
- **Assessor Authentication**: Secure login for qualified assessors
- **Progressive Evaluation**: Step-by-step criteria assessment
- **Scoring System**: Weighted scoring with competency tracking
- **Documentation**: Complete audit trail of assessment results

## Current Limitations

### 1. Data Persistence
- WPA Builder assessments are not permanently stored
- No database integration for assessment management
- Limited to static JSON files for DMT assessments

### 2. Assessment Sync
- No synchronization between WPA Builder and DMT Viewer
- Manual export/import process required
- No real-time updates or collaboration features

### 3. User Management
- Basic assessor authentication without proper user management
- No role-based access control
- Limited tracking of assessment attempts and results

## Firebase Integration Plan

### 1. Data Structure in Firebase

**Firestore Collections:**
```
assessments/
  ├── {assessmentId}/
  │   ├── metadata (document)
  │   ├── assessment (document) 
  │   ├── criteria (subcollection)
  │   ├── poi_assignments (subcollection)
  │   └── results (subcollection)
  │
users/
  ├── {userId}/
  │   ├── profile (document)
  │   ├── assessments_created (subcollection)
  │   └── assessment_results (subcollection)
  │
pois/
  ├── {poiId}/
  │   └── assigned_assessments (array)
```

### 2. Integration Goals
1. **Real-time Sync**: WPA Builder → Firebase → DMT Viewer
2. **Multi-user Support**: Collaborative assessment development
3. **Result Tracking**: Comprehensive assessment analytics
4. **Access Control**: Role-based permissions and security
5. **Offline Support**: Local caching for assessments

## Technical Implementation Notes

### Current Architecture Strengths
- **Modular Design**: Clean separation of concerns
- **Reusable Components**: Well-structured UI components
- **Flexible Data Model**: Extensible JSON structure
- **Progressive Enhancement**: Gradual feature addition

### Areas for Improvement
- **State Management**: Better state synchronization
- **Error Handling**: Robust error recovery
- **Performance**: Optimized data loading
- **Testing**: Comprehensive test coverage

## Conclusion

The WPA system provides a solid foundation for assessment management with clear separation between content creation (WPA Builder) and content delivery (DMT Viewer). The next step is implementing Firebase integration to enable real-time data synchronization and persistent storage, making the system fully functional for production use.

The system's modular architecture and well-defined data structures make it ready for Firebase integration while maintaining backward compatibility with existing JSON-based assessments.