# Participation System

## Purpose
A **shared architecture** for managing event participation across multiple event types (marathons, competitions). Provides a unified workflow for eligibility checks, participation requests, seat allocation, student enrollment, payment processing, and audit trails.

## Architecture

The participation system uses **polymorphic relationships** to share the same models across different event types:

```
Event (Marathon/Assessment/Competition)
  └── EventParticipation (participant = teacher)
       ├── SeatAllocation (seat limits per participant)
       │    └── StudentEnrollment (enrolled students)
       ├── PaymentSubmission (payment records)
       └── ParticipationAudit (audit log)
```

## Config-Driven Behavior
The system is driven by `config/participation.php` which defines:

### Scopes
Three scope levels determine visibility and authority:
- **system** — Event visible to all programs, approved by super-admins
- **program** — Event visible within a program, approved by portal-admins/managers
- **teacher** — Event visible to teacher's students, approved by teacher

### Event Types
- `marathon` — Multi-competition events
- `competition` — Single competition events

### Per-Event-Per-Scope Configuration
Each combination defines:
- `approval_authority` — Roles that can approve participation
- `participant_type` — `teacher` or `student`
- `seat_allocation` — Whether seat limits apply
- `enrollment_modes` — `manual`, `request`
- `payment_required` — Whether payment is needed

## Key Models

### EventParticipation (`app/Models/Participation/EventParticipation.php`)
- **Polymorphic:** `event_type` / `event_id` (morphs to Marathon or Assessment)
- Tracks a teacher's participation in an event
- Has `status` field (pending, approved, rejected, cancelled)
- HasMany: `seatAllocation`, `enrollments`, `payments`, `audits`

### EventEligibility (`app/Models/Participation/EventEligibility.php`)
- **Polymorphic:** `event_type` / `event_id`
- Defines who is eligible to participate in an event
- Can specify eligibility by: program, teacher, level, etc.

### SeatAllocation (`app/Models/Participation/SeatAllocation.php`)
- BelongsTo EventParticipation
- Fields: `total_seats`, `used_seats`, `notes`, `is_locked`
- Computed: `remainingSeats()`
- HasMany: StudentEnrollment
- Scoped: `scopeAvailable()` (used_seats < total_seats)

### StudentEnrollment (`app/Models/Participation/StudentEnrollment.php`)
- **Polymorphic context:** Different morph types for marathon vs competition
- Tracks student enrollment in events
- Has status: pending, approved, rejected, removed
- BelongsTo: EventParticipation, SeatAllocation, User (student)

### PaymentSubmission (`app/Models/Participation/PaymentSubmission.php`)
- **Polymorphic context:** Different morph types for marathon vs competition
- Tracks payment submissions for participation
- Has status: pending, verified, rejected

### ParticipationAudit (`app/Models/Participation/ParticipationAudit.php`)
- **Polymorphic context:** Different morph types
- Records all participation actions with who-did-what-when

## Services

### ParticipationService (`app/Services/Participation/Services/ParticipationService.php`)
- Central orchestration service
- Coordinates all sub-services (Eligibility, Request, Seat, Enrollment, Payment, Audit)

### Specialized Services
- `MarathonParticipationService` — Marathon-specific participation logic
- `CompetitionParticipationService` — Competition-specific participation logic
- `EligibilityService` — Eligibility checking
- `ParticipationRequestService` — Request management (submit, approve, reject)
- `SeatAllocationService` — Seat management (allocate, release)
- `StudentEnrollmentService` — Student enrollment (enroll, approve, reject, remove)
- `PaymentService` — Payment tracking (submit, verify, reject)
- `ParticipationAuditService` — Audit trail recording

### ScopeConfig (`app/Services/Participation/Services/ScopeConfig.php`)
- Helper that reads `config/participation.php` and resolves scope-specific settings
- Methods: `getScope()`, `approvalAuthority()`, `participantType()`, `visibility()`, `eligibleResolver()`, `getRecipients()`

## Contracts
- `EligibilityServiceInterface`, `ParticipationRequestServiceInterface`, `SeatAllocationServiceInterface`
- `StudentEnrollmentServiceInterface`, `PaymentServiceInterface`, `ParticipationAuditServiceInterface`

## Notifications
Participation actions trigger notifications via `config/participation.php` recipient configuration:
- `participation.submitted`, `.approved`, `.rejected`, `.cancelled`
- `enrollment.submitted`, `.approved`, `.rejected`, `.removed`, `.manual`
- `payment.submitted`, `.verified`, `.rejected`
- `seat.allocated`, `.full`

## Authorization Gates
Registered in `AppServiceProvider`:
- `participation.approve` — Approve participation requests
- `participation.enroll-student` — Enroll students
- `participation.verify-payment` — Verify payment submissions
- `participation.view` — View participation records
- `participation.manage-eligibility` — Manage eligibility
- `participation.student-can-join` — Check if student can join
- `participation.manage-event` — Manage event participation

## Filament Pages (Program Panel)
- `EligibilityManagerPage` — Manage event eligibility
- `ParticipationRequestManagementPage` — Manage participation requests
- `PaymentVerificationPage` — Verify payments
- `StudentEnrollmentPage` — Manage student enrollments

## Filament Widgets
- `MarathonParticipationWidget` — Marathon participation overview
- `CompetitionParticipationWidget` — Competition participation overview
- `StudentEnrollmentWidget` — Student enrollment stats
- `TeacherParticipationWidget` — Teacher participation stats
- `ParticipationPendingRequestsWidget` — Pending requests count

## Livewire Components
- `ParticipationRequestsTable` — Table of participation requests
- `ParticipantsTable` — Table of participants
- `EligibilityTable` — Eligibility management table

## Dual-Write Transition
The system supports dual-write (`config/participation.php` → `dual_write_enabled`):
- Writes to both legacy join request models (AssessmentJoinRequest, MarathonJoinRequest) AND new shared participation tables
- Provides backward compatibility during migration

## Related Workflows
- **[Participation Workflow (Shared)](../WORKFLOWS.md#6-participation-workflow-shared)** — End-to-end teacher participation, student enrollment, payment, and audit