# Marathons Module

## Purpose
Marathons are **multi-competition events** that group together multiple competitions under a single themed event with a defined time period.

## Business Context
A marathon is a time-bound event (e.g., "Summer Math Challenge 2026") that contains multiple competitions. Teachers participate in marathons, and their students take the individual competitions within the marathon.

## Key Model — Marathon (`app/Models/Marathon.php`)

### Fields
- `program_id`, `teacher_id` — Ownership
- `scope` (enum): `system`, `program`, `teacher` — Visibility and participation rules
- `title`, `description`, `purpose` (json, translatable)
- `picture` (string, nullable)
- `starts_at`, `ends_at` (datetime)
- `status` — Current state
- `payment_required` (boolean), `enrollment_mode`

### Relationships
- `program()` → BelongsTo Program
- `teacher()` → BelongsTo User
- `competitions()` → HasMany Assessment (where type = competition/marathon-competition)
- `participations()` → MorphMany EventParticipation
- `eligibilities()` → MorphMany EventEligibility

### Scopes
- `scopeSystem()`, `scopeProgram()`, `scopeTeacher()` — Filter by scope

### Lifecycle
- **Created:** Dispatches `marathon.created`
- Auto-completed by scheduler when past end date

## Feature Entitlement

| Feature | Scope | Default Limit |
|---------|-------|---------------|
| `no_of_marathons` | Program | 5 |
| `no_of_competition_per_marathon` | Program | 5 |

## Scheduled Tasks
- `marathons:complete-expired` — Hourly, auto-completes marathons past their end date
- `notifications:marathon-upcoming` — Daily at 8:00 AM, notifies about marathons starting/ending within 24h

## Filament Resources
- `MarathonResource` — CRUD in Program panel
- Includes relation manager for competitions within the marathon

## Marathon Participation Service
- `MarathonParticipationService` — Handles marathon-specific participation logic
- Extends the shared participation architecture

## Related Workflows
- **[Marathon Lifecycle Workflow](../WORKFLOWS.md#5-marathon-lifecycle-workflow)** — End-to-end marathon creation, competition management, and completion
- **[Participation Workflow (Shared)](../WORKFLOWS.md#6-participation-workflow-shared)** — Teacher participation requests, seat allocation, and student enrollment