MGSLG Analytics Platform - Enhancement Plan

MGSLG Analytics Platform - Enhancement Plan

Districts & SACE Points Implementation

Date: January 2025 Status: Planning Phase Client Feedback: Presentation went very well - new requirements identified

---

Executive Summary

Based on client presentation feedback, two major enhancements are required:

1. District-Level Tracking - Add hierarchical district tracking within provinces
2. SACE Points System - Track teacher professional development points for certification

---

1. DISTRICT-LEVEL TRACKING

Business Context

MGSLG operates primarily in Gauteng, which is divided into 15 education districts. Tracking at district level provides:

• More granular geographic analysis
• Better resource allocation per district
• District-specific performance metrics
• Alignment with Gauteng Department of Education structure

Gauteng Education Districts (15 Total)

Johannesburg Region (5 districts):

• Johannesburg Central
• Johannesburg East
• Johannesburg North
• Johannesburg South
• Johannesburg West

Tshwane Region (3 districts):

• Tshwane North
• Tshwane South
• Tshwane West

Ekurhuleni Region (2 districts):

• Ekurhuleni North
• Ekurhuleni South

Gauteng Other (3 districts):

• Gauteng East (Springs)
• Gauteng North
• Gauteng West (Krugersdorp)

Sedibeng Region (2 districts):

• Sedibeng East (Vereeniging)
• Sedibeng West (Sebokeng)

Database Schema Changes

1. Add District Field to Participant Model

# backend/app/models.py - Participant model

class Participant(Base):
    __tablename__ = "participants"

    # Existing fields...
    province: str
    city: str

    # NEW FIELD
    district: Optional[str]  # Education district within province

2. Create District Reference Table (Optional - for data integrity)

# backend/app/models.py - New model

class EducationDistrict(Base):
    __tablename__ = "education_districts"

    id: str  # Primary key
    name: str  # "Johannesburg Central", "Tshwane North", etc.
    province: str  # "Gauteng", "Western Cape", etc.
    region: str  # "Johannesburg", "Tshwane", "Ekurhuleni", etc.
    office_address: Optional[str]
    created_date: datetime

API Changes Required

1. Dashboard API (backend/app/api/routes/dashboard.py)

• Add district filter to all endpoints
• Add district breakdown to geographic distribution
• Create new endpoint: /api/dashboard/district-summary

2. Participants API (backend/app/api/routes/participants.py)

• Add district filter to GET /api/participants
• Include district in participant details
• Add district validation on create/update

3. Programs API

• Filter programs by district
• Track program instances per district

Frontend Changes Required

1. Dashboard Filters

// Add to DashboardFilters.tsx
<select value={filters.district} onChange={handleDistrictChange}>
  <option value="">All Districts</option>
  {districts.map(d => (
    <option key={d} value={d}>{d}</option>
  ))}
</select>

2. Geographic Visualization

• Update province distribution to show district breakdown
• Add district-level bar chart for Gauteng
• Create district comparison view

3. Participant Forms

• Add district dropdown to participant registration/edit forms
• Populate districts based on selected province

Data Migration

Seeding Script Update:

backend/seed_database.py

# Add district assignment logic
def assign_district_to_gauteng_participants():
    """Assign realistic districts to existing Gauteng participants"""
    gauteng_districts = [
        "Johannesburg Central",
        "Johannesburg East",
        # ... all 15 districts
    ]

    # Distribute participants across districts
    # based on realistic population distribution

---

2. SACE POINTS SYSTEM

Business Context

SACE (South African Council for Educators) Points Requirements:

• Teachers must earn 150 CPTD points over 3 years (50 points/year target)
• Mandatory for teacher certification and continued registration
• Points earned through professional development activities

Three Types of Activities:

• Type 1: Teacher-Initiated (self-chosen development)
• Type 2: School-Initiated (school-led activities)
• Type 3: Externally Initiated (SACE-endorsed provider courses) ← MGSLG programs would be Type 3

Database Schema Changes

1. Add SACE Points Configuration to Programs

# backend/app/models.py - Program model

class Program(Base):
    __tablename__ = "programs"

    # Existing fields...
    name: str
    category: ProgramCategoryEnum
    duration_days: int

    # NEW FIELDS
    sace_points: Optional[int]  # Points awarded upon completion
    sace_activity_type: Optional[str]  # "Type 1", "Type 2", "Type 3"
    sace_accredited: bool = False  # Is this SACE-endorsed?
    sace_accreditation_number: Optional[str]  # Official SACE number

2. Track SACE Points in Enrollments

# backend/app/models.py - Enrollment model

class Enrollment(Base):
    __tablename__ = "enrollments"

    # Existing fields...
    completion_status: CompletionStatusEnum
    completion_date: Optional[datetime]

    # NEW FIELDS
    sace_points_awarded: Optional[int]  # Points awarded upon completion
    sace_points_date: Optional[datetime]  # When points were awarded
    sace_certificate_issued: bool = False  # Certificate issued?

3. Create Participant SACE Summary Table

# backend/app/models.py - New model

class ParticipantSACEPoints(Base):
    __tablename__ = "participant_sace_points"

    id: str  # Primary key
    participant_id: str  # Foreign key to Participant

    # SACE Points Summary
    total_points_earned: int  # Lifetime total
    points_current_cycle: int  # Current 3-year cycle (0-150)
    cycle_start_date: datetime  # When current cycle started
    cycle_end_date: datetime  # When current cycle ends

    # Breakdown by type
    type1_points: int  # Teacher-initiated
    type2_points: int  # School-initiated
    type3_points: int  # Externally initiated (MGSLG programs)

    # Status
    is_compliant: bool  # Meeting 50 points/year target?
    compliance_status: str  # "On Track", "At Risk", "Behind"

    last_updated: datetime

API Changes Required

1. New ML Analytics Endpoint

backend/app/api/routes/ml_analytics_real.py

@router.get("/sace-compliance-prediction")
async def predict_sace_compliance(
    participant_id: Optional[str] = None,
    db: AsyncSession = Depends(get_db)
):
    """
    Predict if participants will meet 150 SACE points requirement.

    Returns:
    - Compliance probability
    - Points projection for current cycle
    - Recommended interventions
    - At-risk participants
    """

2. New Dashboard Endpoint

backend/app/api/routes/dashboard.py

@router.get("/sace-summary")
async def get_sace_summary(db: AsyncSession = Depends(get_db)):
    """
    SACE Points dashboard summary.

    Returns:
    - Total points awarded (all time)
    - Participants by compliance status
    - Average points per participant
    - Points distribution by program
    """

3. Participant SACE Points Endpoint

backend/app/api/routes/participants.py

@router.get("/{participant_id}/sace-points")
async def get_participant_sace_points(
    participant_id: str,
    db: AsyncSession = Depends(get_db)
):
    """
    Get participant's SACE points history and compliance status.

    Returns:
    - Total points earned
    - Current cycle progress (0-150)
    - Points by program
    - Compliance status
    - Certificate history
    """

Frontend Changes Required

1. New SACE Dashboard Section

frontend/src/components/SACEDashboard.tsx

interface SACESummary {
  totalPointsAwarded: number;
  averagePointsPerParticipant: number;
  compliantParticipants: number;
  atRiskParticipants: number;
  pointsByProgram: Array<{
    programName: string;
    totalPoints: number;
    participantCount: number;
  }>;
}

2. Participant SACE Profile

// Add to ParticipantDetail.tsx

<div className="sace-points-card">
  <h3>SACE Points Summary</h3>
  <div className="progress-ring">
    <ProgressRing
      percentage={saceSummary.currentCycleProgress}
      label={`${saceSummary.pointsCurrentCycle}/150 Points`}
    />
  </div>
  <div className="compliance-status">
    Status: {saceSummary.complianceStatus}
  </div>
  <div className="points-breakdown">
    <div>Type 1: {saceSummary.type1Points}</div>
    <div>Type 2: {saceSummary.type2Points}</div>
    <div>Type 3: {saceSummary.type3Points}</div>
  </div>
</div>

3. Program SACE Configuration

// Add to Program management forms

<div className="sace-config">
  <label>
    <input type="checkbox" name="saceAccredited" />
    SACE Accredited Program
  </label>
  {saceAccredited && (
    <>
      <input
        type="number"
        name="sacePoints"
        placeholder="SACE Points Awarded"
      />
      <select name="saceActivityType">
        <option value="Type 1">Type 1 - Teacher-Initiated</option>
        <option value="Type 2">Type 2 - School-Initiated</option>
        <option value="Type 3">Type 3 - Externally Initiated</option>
      </select>
      <input
        type="text"
        name="saceAccreditationNumber"
        placeholder="SACE Accreditation Number"
      />
    </>
  )}
</div>

Data Seeding Strategy

1. Assign SACE Points to Existing Programs

# Example SACE points assignment

PROGRAM_SACE_POINTS = {
    "Educational Leadership": 40,  # Long program, high points
    "Curriculum Development": 30,
    "Assessment Strategies": 25,
    "Digital Teaching Tools": 20,
    "Inclusive Education": 25
}

# Update programs with SACE configuration
for program_name, points in PROGRAM_SACE_POINTS.items():
    program.sace_points = points
    program.sace_activity_type = "Type 3"
    program.sace_accredited = True

2. Calculate Historical SACE Points

# Backfill SACE points for completed enrollments

for enrollment in completed_enrollments:
    if enrollment.program.sace_accredited:
        enrollment.sace_points_awarded = enrollment.program.sace_points
        enrollment.sace_points_date = enrollment.completion_date
        enrollment.sace_certificate_issued = True

3. Generate Participant SACE Summaries

# Calculate each participant's SACE status

def calculate_participant_sace_summary(participant):
    completed_programs = get_completed_programs(participant.id)
    total_points = sum(p.sace_points_awarded for p in completed_programs)

    # Calculate current 3-year cycle
    cycle_start = datetime.now() - timedelta(days=3*365)
    recent_points = sum(
        p.sace_points_awarded
        for p in completed_programs
        if p.completion_date >= cycle_start
    )

    # Determine compliance status
    years_in_cycle = (datetime.now() - cycle_start).days / 365
    expected_points = years_in_cycle * 50
    compliance_status = "On Track" if recent_points >= expected_points else "At Risk"

    return ParticipantSACEPoints(
        participant_id=participant.id,
        total_points_earned=total_points,
        points_current_cycle=recent_points,
        compliance_status=compliance_status,
        # ...
    )

---

3. IMPLEMENTATION PHASES

Phase 1: Database Schema & Migration (Week 1)

Priority: HIGH - Foundation for all other work

Tasks:

1. Create database migration scripts

   • Add district field to Participant model
   • Create EducationDistrict reference table
   • Add SACE fields to Program model
   • Add SACE fields to Enrollment model
   • Create ParticipantSACEPoints table

2. Seed district data

   • Populate 15 Gauteng districts
   • Assign districts to existing 1,500 participants

3. Seed SACE points data

   • Configure SACE points for all 5 programs
   • Backfill SACE points for completed enrollments
   • Generate SACE summaries for all participants

Deliverables:

• Migration scripts executed successfully
• All existing data has district assignments
• All programs have SACE configuration
• SACE points calculated for all participants

Testing:

• Verify 1,500 participants have valid districts
• Verify SACE points calculations are accurate
• Check data integrity (no nulls where required)

---

Phase 2: Backend API Implementation (Week 1-2)

Priority: HIGH - Required for frontend integration

Tasks:

1. Update existing endpoints

   • Add district filtering to dashboard endpoints
   • Add district to participant GET/POST/PUT
   • Include SACE points in enrollment responses

2. Create new endpoints

   • /api/dashboard/district-summary - District-level metrics
   • /api/dashboard/sace-summary - SACE points dashboard
   • /api/participants/{id}/sace-points - Individual SACE profile
   • /api/ml/sace-compliance-prediction - ML predictions

3. Update ML Analytics

   • Extend enrollment forecasting with district breakdown
   • Add SACE compliance prediction algorithm
   • Generate at-risk participant alerts

Deliverables:

• All API endpoints documented and tested
• Swagger/OpenAPI documentation updated
• Unit tests for new endpoints (>80% coverage)

Testing:

• Test all endpoints with Postman/curl
• Verify filtering works correctly
• Performance testing (response times <200ms)

---

Phase 3: Frontend UI Implementation (Week 2-3)

Priority: MEDIUM - User-facing features

Tasks:

1. Dashboard Updates

   • Add district filter dropdown
   • Create district distribution chart
   • Add SACE summary cards
   • Create SACE compliance chart

2. Participant Management

   • Add district field to forms
   • Create SACE points profile section
   • Display SACE compliance status badge

3. New Pages/Components

   • SACEDashboard.tsx - Dedicated SACE analytics page
   • DistrictAnalytics.tsx - District comparison view
   • Navigation updates to include new pages

Deliverables:

• All UI components functional
• Responsive design maintained
• Consistent styling with existing UI

Testing:

• Cross-browser testing (Chrome, Firefox, Safari)
• Mobile responsive testing
• User acceptance testing

---

Phase 4: Documentation & Training (Week 3)

Priority: MEDIUM - Stakeholder enablement

Tasks:

1. Update documentation

   • Update DEPLOYMENT_GUIDE.md
   • Update API documentation
   • Create USER_GUIDE.md

2. Create training materials

   • How to use district filtering
   • Understanding SACE compliance metrics
   • How to configure SACE points for programs

3. Update presentation materials

   • Add district analytics slides
   • Add SACE points demonstration
   • Update business value sections

Deliverables:

• Comprehensive documentation
• Training video/guide
• Updated presentation deck

---

Phase 5: Deployment & Validation (Week 3-4)

Priority: HIGH - Production readiness

Tasks:

1. Railway deployment

   • Deploy updated backend with migrations
   • Deploy updated frontend
   • Verify production database migration

2. Data validation

   • Verify all 1,500 participants have districts
   • Verify SACE points calculations are correct
   • Run integrity checks

3. Performance optimization

   • Database query optimization
   • Frontend loading optimization
   • Caching strategy for SACE calculations

Deliverables:

• Production deployment successful
• All features working in production
• Performance metrics meet targets

Testing:

• End-to-end testing in production
• Load testing (concurrent users)
• Stakeholder acceptance testing

---

4. TECHNICAL CONSIDERATIONS

Database Performance

• Add indexes on district field for faster filtering
• Add indexes on sace_points_awarded for aggregations
• Consider materialized view for SACE summary calculations

Data Integrity

• Validate district values against reference table
• Ensure SACE points only awarded for SACE-accredited programs
• Prevent duplicate SACE point awards

Edge Cases

• What happens if participant moves districts? (Track history?)
• SACE points for partially completed programs? (No points until completion)
• Manual SACE point adjustments? (Admin interface needed?)

Security

• Only authorized users can view SACE points details
• Audit trail for SACE certificate issuance
• Secure SACE accreditation numbers (sensitive data)

---

5. SUCCESS METRICS

District Tracking

• 100% of participants have valid district assignments
• District filtering works across all dashboard views
• District-level reports available for all metrics

SACE Points System

• 100% of programs have SACE configuration
• 100% of completed enrollments have SACE points calculated
• SACE compliance predictions available for all participants
• At-risk participants identified with >85% accuracy

Performance

• API response times remain <200ms
• Dashboard load time <2 seconds
• Database queries optimized (no N+1 queries)

User Adoption

• Stakeholders actively using district filters
• SACE compliance reports requested regularly
• Positive user feedback on new features

---

6. RISKS & MITIGATION

Risk 1: Inaccurate SACE Points Assignment

Impact: HIGH - Incorrect compliance reporting could affect teacher certifications Mitigation:

• Cross-reference with official SACE documentation
• Implement manual review process for SACE configuration
• Add admin interface to correct SACE point errors

Risk 2: District Data Quality

Impact: MEDIUM - Incorrect districts could skew analytics Mitigation:

• Validate districts against official Gauteng DoE list
• Allow participants to update their district
• Regular data quality audits

Risk 3: Performance Degradation

Impact: MEDIUM - Additional fields and calculations could slow system Mitigation:

• Database indexing strategy
• Caching for expensive calculations
• Performance testing before deployment

Risk 4: Scope Creep

Impact: MEDIUM - Additional requirements could delay delivery Mitigation:

• Clear phase definitions with acceptance criteria
• Regular stakeholder check-ins
• MVP approach - deliver core features first

---

7. NEXT STEPS

Immediate Actions (This Week)

1. ✅ Research SACE points requirements (COMPLETED)
2. ✅ Research Gauteng districts (COMPLETED)
3. ✅ Create enhancement plan (COMPLETED)
4. ⏳ Get stakeholder approval on plan
5. ⏳ Begin Phase 1: Database schema design

Awaiting Approval

• Enhancement plan review and approval
• Budget/timeline confirmation
• Resource allocation
• Priority confirmation (districts vs SACE - implement together or phased?)

Questions for Stakeholder

1. Should we implement districts for ALL provinces or just Gauteng initially?
2. Do other provinces have district structures we should plan for?
3. What SACE point values should be assigned to each program? (Need official accreditation?)
4. Is there a deadline for these enhancements?
5. Should we add SACE certificate generation/printing functionality?

---

8. ESTIMATED EFFORT

Development Time

• Phase 1 (Database): 3-4 days
• Phase 2 (Backend): 5-7 days
• Phase 3 (Frontend): 7-10 days
• Phase 4 (Documentation): 2-3 days
• Phase 5 (Deployment): 2-3 days

Total Estimated Time: 19-27 days (3-4 weeks)

Team Requirements

• Backend Developer: 10-12 days
• Frontend Developer: 7-10 days
• Database Engineer: 3-4 days
• QA/Testing: 3-4 days
• Technical Writer: 2-3 days

---

APPENDIX A: Database Schema Diagrams

Districts Implementation

Participant
├── id (PK)
├── province ─────┐
├── district ─────┼─→ EducationDistrict
└── city          │   ├── id (PK)
                  │   ├── name
                  └───├── province (FK)
                      ├── region
                      └── office_address

SACE Points Implementation

Program                     Enrollment                   ParticipantSACEPoints
├── id (PK)                ├── id (PK)                  ├── id (PK)
├── name                   ├── participant_id (FK) ────→├── participant_id (FK)
├── sace_points            ├── program_instance_id      ├── total_points_earned
├── sace_activity_type     ├── completion_status        ├── points_current_cycle
├── sace_accredited        ├── sace_points_awarded ──┐  ├── type1_points
└── sace_accreditation_no  └── sace_certificate_issued │  ├── type2_points
                                                        │  ├── type3_points
                                                        └→ └── compliance_status

---

Document Version: 1.0 Last Updated: 2025-01-XX Author: Development Team Status: Awaiting Stakeholder Approval