# Core Services

## Overview
Documentation of the primary business logic services that orchestrate operations across modules.

## Subscription Services

### SubscriptionService (`app/Services/SubscriptionService.php`)
- **Singleton** registered in `AppServiceProvider`
- Central facade for subscription lifecycle operations
- Handles: subscribe, unsubscribe, plan change, renewal, suspension
- Instantiates auto-subscriptions for new users/programs
- Accepts `NotificationEngine` dependency for dispatching subscription events

### SubscriptionRequestService (`app/Services/SubscriptionRequestService.php`)
- **Singleton** registered in `AppServiceProvider`
- Manages subscription upgrade/downgrade requests
- Handles approval workflow for plan changes

### Subscriptions Package Integration (`app/Services/Subscriptions/`)
- `SubscriptionHistoryService` — Records subscription lifecycle changes
- `RenewalWorkflow` — Handles subscription renewals with proration
- `PlanChangeWorkflow` — Handles plan changes with proration
- `NotificationHandler` — Sends subscription notifications
- `ProrationCalculator` — Calculates prorated charges
- Contracts: `SubscriptionServiceInterface`, `SubscriptionNotificationInterface`

## Participation Services (`app/Services/Participation/`)

Centralized in `ParticipationService` with specialized services:
- `EligibilityService` — Checks eligibility criteria against config
- `ParticipationRequestService` — CRUD for participation requests
- `SeatAllocationService` — Manages seat limits with atomic counters
- `StudentEnrollmentService` — Manages student enrollment in events
- `PaymentService` — Tracks payment submissions
- `ParticipationAuditService` — Records audit trail
- `MarathonParticipationService` — Marathon-specific orchestration
- `CompetitionParticipationService` — Competition-specific orchestration
- `ScopeConfig` — Reads participation configuration

## Payment Services (`app/Services/Payments/`)
- `PaymentService` — Singleton, handles payment processing
- `OfflinePaymentGateway` — Current implementation (offline/manual payments)
- Contracts: `PaymentGatewayContract`

## RankingService (`app/Services/RankingService.php`)
- Computes rankings for competitions and marathons
- Used by Filament widgets for leaderboards

## MarathonService (`app/Services/MarathonService.php`)
- **Singleton** registered in `AppServiceProvider`
- Manages marathon lifecycle (create, complete)
- Handles marathon-specific business rules

## Other Services
- `FileService` — File management utilities
- `ProblemService` — Assessment problem generation
- `AssessmentProblemsExportService` — Export problems to Excel
- `WhatsAppService` — WhatsApp messaging integration (via backend/ executables)
- `TranslationManager` — Translation management
- `NotificationService` — Legacy notification support

## FeatureEntitlement Services
See [Feature Entitlement](feature-entitlement.md) for detailed documentation:
- `FeatureGate` — Central feature check/consume/release
- `FeatureResolver` — Resolve feature values from plans
- `FeatureDefinition` — Read feature definitions
- `UsageTracker` — Track consumption counters