---
name: achievements-system
description: AchievementEngine, AchievementRepository, milestone checkers, AchievementsSeeder, user_achievements pivot, AchievementsController API, and achievement evaluation flow.
---

# Achievements System

Milestone-based achievements unlocked when users hit thresholds for uploads, streaks, and per-tag counts. Definitions are seeded from `config/achievements.php` milestones crossed with every tag in the system.

## Key Files

- `config/achievements.php` — Milestones array, cache TTL, level thresholds
- `app/Services/Achievements/AchievementEngine.php` — Core evaluator (checkers + fallback pass)
- `app/Services/Achievements/AchievementRepository.php` — DB reads/writes + caching
- `app/Services/Achievements/Checkers/AchievementChecker.php` — Abstract base checker
- `app/Services/Achievements/Checkers/UploadsChecker.php` — Uploads dimension
- `app/Services/Achievements/Checkers/ObjectsChecker.php` — Objects dimension + per-object
- `app/Services/Achievements/Checkers/CategoriesChecker.php` — Categories dimension + per-category
- `app/Services/Achievements/Checkers/MaterialsChecker.php` — Materials (extends OptimizedTagBasedChecker)
- `app/Services/Achievements/Checkers/BrandsChecker.php` — Brands (extends OptimizedTagBasedChecker)
- `app/Services/Achievements/Checkers/CustomTagChecker.php` — Custom tags (extends OptimizedTagBasedChecker)
- `app/Services/Achievements/Checkers/OptimizedTagBasedChecker.php` — Abstract base for tag-based checkers
- `app/Services/Achievements/Tags/TagKeyCache.php` — Tag key-to-ID resolution cache
- `app/Providers/AchievementServiceProvider.php` — DI wiring (engine, repository, checkers)
- `app/Models/Achievements/Achievement.php` — Eloquent model
- `app/Events/AchievementsUnlocked.php` — Event fired when achievements unlock
- `app/Http/Controllers/Achievements/AchievementsController.php` — API endpoint
- `database/seeds/AchievementSeeder.php` — Seeds achievement definitions
- `database/factories/AchievementFactory.php` — Test factory
- `tests/Feature/Achievements/AchievementEngineTest.php` — Engine integration tests
- `tests/Feature/Achievements/LongTermAchievementsTest.php` — Long-term achievement tests
- `tests/Unit/Achievements/CheckerUnitTest.php` — Checker unit tests

## Invariants

1. **Achievements are evaluated after Redis metrics update.** `AchievementEngine::evaluate()` reads from `RedisMetricsCollector::getUserMetrics()`. Redis must be updated first.
2. **Definitions are seeded, not runtime-created.** `AchievementsSeeder` creates all definition rows. Adding a new tag type or milestone requires rerunning the seeder.
3. **`user_achievements` pivot has composite PK `(user_id, achievement_id)`.** `insertOrIgnore` prevents duplicates.
4. **Checkers use early-exit optimization.** Achievements sorted by threshold ascending — once a threshold isn't met, remaining are skipped.
5. **Fallback pass in engine catches checker gaps.** `meetsThreshold()` runs after all checkers, catching anything they missed (safety net for off-by-one or unregistered checkers).
6. **Caching:** Definitions cached 24h (`achievements.all`), per-user unlocked cached 5m (`user.achievements.$userId`). Cache cleared on unlock.

## Architecture

```
Photo tagged + verified
  → TagsVerifiedByAdmin event
    → ProcessPhotoMetrics listener
      → MetricsService::processPhoto() (MySQL + Redis)
      → EvaluateUserAchievements job (queued)
        → AchievementEngine::evaluate($userId)
          → RedisMetricsCollector::getUserMetrics($userId)
          → Run all registered checkers
          → Fallback meetsThreshold() pass
          → AchievementRepository::unlockAchievements()
          → Cache invalidation
```

## Achievement Types

| Type | Scope | Example |
|------|-------|---------|
| `uploads` | Dimension-wide (no tag_id) | "Upload 42 photos" |
| `streak` | Dimension-wide (no tag_id) | "7-day upload streak" |
| `objects` | Dimension-wide (no tag_id) | "Tag 1000 total objects" |
| `object` | Per-tag (tag_id = litter_object.id) | "Tag 69 cigarette butts" |
| `categories` | Dimension-wide (no tag_id) | "Tag items in 10 categories" |
| `category` | Per-tag (tag_id = category.id) | "Tag 256 smoking items" |
| `materials` | Dimension-wide (no tag_id) | "Tag 500 total materials" |
| `material` | Per-tag (tag_id = material.id) | "Tag 42 plastic items" |
| `brands` | Dimension-wide (no tag_id) | "Tag 100 total brands" |
| `brand` | Per-tag (tag_id = brand.id) | "Tag 69 Coca-Cola items" |
| `customTag` | Per-tag (tag_id = custom_tag.id) | Per custom tag milestones |

## Milestones

From `config/achievements.php`:
```
[1, 42, 69, 256, 360, 404, 420, 451, 512, 666, 777, 1337, 2048, 3333, 3600, 9001, 13337, 42069, 69420, 133337, 420420, 666666, 696969, 4206969]
```

Each milestone is crossed with each type/tag combination, producing ~222k achievement definitions.

## API

`GET /api/achievements` (auth required) — Returns hierarchical JSON:
- `overview`: progress for uploads, streak, total_categories, total_objects
- `categories`: per-category with nested per-object progress
- `summary`: total/unlocked/percentage

## Common Mistakes

- **Evaluating before Redis is updated.** `getUserMetrics()` reads from Redis. If called before `RedisMetricsCollector::processPhoto()`, counts are stale.
- **Forgetting to reseed after adding tags.** New LitterObjects/Materials/Brands need new achievement definition rows.
- **Assuming checkers cover all types.** The fallback `meetsThreshold()` is the safety net. If a checker is missing, achievements still unlock (just slower).