# Elmeg Platform Audit & Implementation Plan
>
> **Date**: December 22, 2024

---

## Executive Summary

This audit examines the Elmeg platform against spec'd features, user stories, and interaction gaps. The platform has strong core functionality but has several incomplete areas that impact user experience.

---

## 🔴 Critical Gaps (High Priority)

### 1. Email System Not Functional

**Status**: Backend model ready, email sending not implemented

**Impact**: Users cannot:

- Verify their email addresses
- Reset passwords
- Receive notification emails

**User Stories Affected**:

- ❌ "As a new user, I want to receive a verification email"
- ❌ "As a user, I want to reset my password if I forgot it"

**Fix Required**:

- Implement `backend/services/email_service.py`
- Integrate with AWS SES (docs exist at `AWS_SES_SETUP.md`)
- Connect auth endpoints to email service

---

### 2. XP Not Actually Awarded

**Status**: Models and endpoints exist, but XP isn't awarded on actions

**Impact**: Gamification system is purely cosmetic - actions don't increase XP

**User Stories Affected**:

- ❌ "As a user, I want to earn XP when I rate a performance"
- ❌ "As a user, I want to earn XP when I mark attendance"

**Fix Required**:

- Hook `award_xp()` into attendance, rating, review endpoints
- Call `check_and_award_badges()` after XP-earning actions

---

### 3. Frontend Not Using Slug URLs

**Status**: API supports slugs, frontend still uses numeric IDs

**Impact**: URLs are non-memorable (e.g., `/songs/69` instead of `/songs/tweezer`)

**Fix Required**:

- Update all `<Link>` components to use slug
- Add slug to API response schemas
- Update frontend routing to accept slug params

---

## 🟡 Important Gaps (Medium Priority)

### 4. Onboarding Flow Incomplete

**Status**: `/welcome` page exists but is minimal

**Gaps**:

- No guided tour for new users
- No prompt to set up profile
- No progressive disclosure of features

**User Stories Affected**:

- ❌ "As a new user, I want a guided introduction to the platform"

---

### 5. Chase Song "Mark as Caught" Not Wired

**Status**: Backend endpoint exists, no frontend UI

**Impact**: Users can add chase songs but can't mark them as caught at shows

**Fix Required**:

- Add "Mark Caught" button on show detail page
- Connect to `POST /chase/songs/{id}/caught`

---

### 6. Performance Rating Disconnected

**Status**: RatingInput component exists, not connected to performances

**Impact**: Users can see ratings but can't submit their own on performance pages

**Fix Required**:

- Wire up `POST /ratings` endpoint on performance detail page
- Award XP when rating is submitted

---

### 7. Notification Center Empty

**Status**: Backend + frontend components exist, no triggers

**Impact**: Bell icon in header shows nothing useful

**Fix Required**:

- Create notifications on: ratings received, badge earned, reply to comment
- Add notification sound/toast for new notifications

---

### 8. Groups Feature Skeletal

**Status**: CRUD exists, no member activity

**Gaps**:

- Can't see what members are doing
- No group leaderboards
- No group chat/discussions

---

## 🟢 Working Features (Verified)

| Feature | Status | Notes |
|---------|--------|-------|
| User registration/login | ✅ | Works |
| Show/Song/Venue browsing | ✅ | Working |
| Performance detail pages | ✅ | With navigation |
| Slug-based API lookups | ✅ | All entities |
| Comment sections | ✅ | Threaded |
| Review system | ✅ | With ratings |
| Chase song list | ✅ | Add/remove works |
| Attendance tracking | ✅ | Basic |
| Profile page | ✅ | With stats |
| Activity feed | ✅ | Global |
| Heady Version display | ✅ | Top performances |
| Admin panel | ✅ | User/content management |
| Mod panel | ✅ | Reports/nicknames |
| Theme toggle | ✅ | Light/dark |
| Settings/preferences | ✅ | Wiki mode |

---

## 📋 Implementation Plan

### Sprint 1: Critical Infrastructure (Est. 4-6 hours)

#### 1.1 Email Service Integration

```
- [ ] Create EmailService class with AWS SES
- [ ] Implement send_verification_email()
- [ ] Implement send_password_reset_email()
- [ ] Wire up auth endpoints
- [ ] Test email flow end-to-end
```

#### 1.2 XP Award Hooks

```
- [ ] Hook award_xp() into attendance.py
- [ ] Hook award_xp() into reviews.py
- [ ] Hook award_xp() into ratings endpoint
- [ ] Call check_and_award_badges() automatically
- [ ] Add "XP earned" toast feedback on frontend
```

---

### Sprint 2: URL & UX Polish (Est. 3-4 hours)

#### 2.1 Slug URLs on Frontend

```
- [ ] Add slug to Song, Show, Venue, Performance response schemas
- [ ] Update Link components to use slug
- [ ] Verify all routes work with slugs
- [ ] Update internal links in ActivityFeed
- [ ] Update search results to use slugs
```

#### 2.2 Performance Rating Widget

```
- [ ] Add RatingInput to performance detail page
- [ ] Connect to POST /ratings endpoint
- [ ] Show user's existing rating if any
- [ ] Animate rating confirmation
- [ ] Award XP on rating
```

---

### Sprint 3: Feature Completion (Est. 4-5 hours)

#### 3.1 Chase Song Completion

```
- [ ] Add "Mark Caught" button on show detail page
- [ ] Show user's chase songs that match show setlist
- [ ] Animate "caught" celebration
- [ ] Award badge for catching 5 songs
```

#### 3.2 Notification Triggers

```
- [ ] Create notification on badge earned
- [ ] Create notification on comment reply
- [ ] Create notification on review reaction
- [ ] Add toast/sound for new notifications
```

#### 3.3 Onboarding Experience

```
- [ ] Create multi-step welcome wizard
- [ ] Prompt profile setup (bio, avatar)
- [ ] Highlight key features
- [ ] Set first badge on completion
```

---

### Sprint 4: Social Enhancement (Est. 3-4 hours)

#### 4.1 XP Leaderboard Integration

```
- [ ] Add XP leaderboard to home page
- [ ] Add leaderboard to /leaderboards page
- [ ] Add "Your Rank" indicator
- [ ] Weekly/monthly/all-time views
```

#### 4.2 Groups Upgrade

```
- [ ] Show member activity in group
- [ ] Group XP leaderboard
- [ ] Group attendance stats
```

---

## 📊 Priority Matrix

| Item | Impact | Effort | Priority |
|------|--------|--------|----------|
| Email service | High | Medium | P1 |
| XP award hooks | High | Low | P1 |
| Slug URLs on frontend | Medium | Low | P2 |
| Performance rating widget | High | Low | P2 |
| Chase "Mark Caught" | Medium | Low | P2 |
| Notification triggers | Medium | Medium | P3 |
| Onboarding wizard | Medium | Medium | P3 |
| Groups enhancement | Low | High | P4 |

---

## Recommended Execution Order

1. **Now**: XP award hooks (quick win, high impact)
2. **Today**: Performance rating widget
3. **Today**: Slug URLs on frontend
4. **Next**: Email service (requires AWS config)
5. **Next**: Chase song completion
6. **Later**: Notifications, onboarding, groups

---

## Quick Wins (Can Do in 30 min each)

1. ✨ Wire XP awards to attendance/review endpoints
2. 🎯 Add performance rating widget
3. 🔗 Update frontend links to use slugs
4. 🏆 Add XP leaderboard to home page
5. 🎵 Add "Mark Caught" button to show pages