# Backend Extension Points

This backend MVP has a static World Cup 2026 seed set and local development auth, but the service boundaries are designed so the product can become a live football rewards ecosystem without replacing core gamification logic.

## 1. Real match data providers

Use `fan_passport.match_ingestion` as the provider boundary.

- A provider implements `MatchDataProvider.fetch_snapshots(since=...)`.
- It returns `ExternalMatchSnapshot` objects with normalized teams, stadiums, scores, status, and provider metadata.
- `MatchIngestionEngine` validates snapshots, computes stable fingerprints, and writes through a `MatchSnapshotRepository`.
- Production should implement `MatchSnapshotRepository` with the existing database/session layer, mapping provider IDs to canonical match/team/stadium records.
- The provided `scripts/ingest_matches.py` validates a JSON feed contract end-to-end before a live vendor API is connected.

Recommended live ingestion flow:

1. Fetch provider snapshots since the last successful provider cursor.
2. Normalize provider status codes through `coerce_match_status`.
3. Run `MatchIngestionEngine.ingest(..., strict=False)` and persist the report.
4. Re-run gamification event evaluation for changed full-time matches.
5. Alert operators if rejected snapshots or low-confidence warnings appear.

Local dry-run example after installing the project:

```bash
python scripts/ingest_matches.py examples/match_feed_sample.json --provider sample-feed
```

## 2. Authentication

The MVP already isolates request identity in the auth/dependency layer. A production auth adapter should keep downstream route/service signatures stable by returning the same internal user identity shape while replacing only token verification.

Recommended production replacements:

- JWT verification against Auth0, Cognito, Firebase Auth, Clerk, or an internal IdP.
- Account linking for email, FIFA/football partner IDs, and social login.
- Role claims for `content:write`, `content:delete`, `content:admin`, moderation, and support tooling.
- Rate limits and abuse signals attached to the request identity before quiz/prediction submissions.

## 3. Moderation

Use `fan_passport.moderation` for deterministic first-pass screening.

Moderated fields should include:

- Display names shown on leaderboards.
- Profile bios and country/team affinity labels.
- Prediction notes or share captions.
- Any future sticker-trade messages or fan-wall comments.

`TextModerator` returns structured findings and can open a `ModerationCase` via `ModerationRepository`. Production can store cases in the database and add a human review UI. The local policy is intentionally deterministic; a third-party moderation API can be added as a second-stage reviewer while preserving the same result/case schema.

## 4. Admin content updates

Use `fan_passport.admin_content` for safe content changes.

The service supports:

- Permission enforcement through `AdminActor.permissions`.
- Change-set validation for teams, stadiums, matches, quiz questions, challenges, badges, stickers, trivia packs, and future competitions.
- Optimistic revision checks with `expected_revision`.
- Dry-runs and deterministic fingerprints.
- Audit event recording for every planned or applied change set.

Recommended production flow:

1. Admin/CMS builds a `ContentChangeSet`.
2. Backend calls `AdminContentService.plan` and shows warnings/errors.
3. Backend applies accepted changes with `AdminContentService.apply`.
4. Applied changes emit analytics/audit events and invalidate relevant leaderboard/content caches.
5. Destructive changes require `content:delete` or `content:admin`.

The `scripts/validate_content_changeset.py` command validates a change-set JSON file with the same rules used by the service layer:

```bash
python scripts/validate_content_changeset.py examples/content_changeset_sample.json
```

## 5. Future football competitions

Use `fan_passport.competition_registry`.

Every future passport should have a namespace of the form:

```text
<competition-slug>:<season-label>
```

Examples:

- `world-cup:2026`
- `premier-league:2026-27`
- `champions-league:2026-27`

Use registry helpers to derive content keys and leaderboard keys instead of embedding World Cup-specific IDs in services. `build_default_registry()` includes World Cup 2026 plus roadmap definitions for Premier League and Champions League. Production can replace these definitions from a JSON file, admin CMS, or database table.

## 6. Operational safety checklist

Before connecting a live provider or admin CMS:

- Implement repository adapters using the existing database transaction/session pattern.
- Make ingestion and content application idempotent.
- Persist ingestion reports and admin audit IDs.
- Recompute achievements after authoritative match status changes.
- Protect write endpoints with role permissions and CSRF/session controls where applicable.
- Run automated tests plus a dry-run seed import on a clean database.