fediversion/.specify/specs/fediversion-multi-band.md

# Feature Specification: Fediversion - Multi-Band Jam Platform

**Feature Branch**: `001-fediversion-multi-band`  
**Created**: 2025-12-28  
**Status**: Draft  
**Input**: Expand elmeg.xyz (Goose) to support Grateful Dead, Dead & Company, Phish, and Billy Strings

---

## Executive Summary

Fediversion is a unified "HeadyVersion" platform for multiple jam bands. It extends the proven elmeg.xyz architecture to support multiple "verticals" (bands) while sharing common infrastructure for users, social features, and the core setlist/performance tracking system.

---

## User Scenarios & Testing

### User Story 1 - Cross-Band Discovery (Priority: P1)

A jam band fan visits the platform and can browse shows and performances across multiple bands they follow (Phish, Dead & Company, Billy Strings) from a single account.

**Why this priority**: This is the core value proposition - one account, all bands.

**Independent Test**: User can register once, mark attendance at shows from different bands, and see unified activity feed.

**Acceptance Scenarios**:

1. **Given** a logged-in user, **When** they navigate to the band selector, **Then** they see all supported bands (Goose, Phish, Grateful Dead, Dead & Company, Billy Strings)
2. **Given** a user on Phish section, **When** they click a show, **Then** they see the full setlist with performance pages
3. **Given** a user with attendance records on multiple bands, **When** they view their profile, **Then** attendance is organized by band

---

### User Story 2 - Phish Fan Migration (Priority: P1)

A Phish fan can access complete setlist data, rate performances, and track their show attendance with the same depth as Phish.net but with enhanced social features.

**Why this priority**: Phish has the most complete API and largest community.

**Independent Test**: User can browse Phish shows from 1983-present, view setlists, rate performances, and see gap statistics.

**Acceptance Scenarios**:

1. **Given** complete Phish data import, **When** user searches "Tweezer", **Then** they see all 600+ performances with dates
2. **Given** a Phish show page, **When** user views setlist, **Then** they see Set 1, Set 2, Encore with segue indicators (>)

---

### User Story 3 - Dead Family Navigation (Priority: P2)

A Deadhead can navigate between Grateful Dead, Dead & Company, and related projects, with song history spanning the entire lineage.

**Why this priority**: Dead family bands share repertoire, enabling unique cross-band song tracking.

**Independent Test**: User can view "Dark Star" song page showing performances across GD, D&C, and side projects.

**Acceptance Scenarios**:

1. **Given** a song played by both GD and D&C, **When** user views song stats, **Then** they see aggregate and per-band breakdowns
2. **Given** D&C show page, **When** viewing performance, **Then** user can see "also played by Grateful Dead X times"

---

### User Story 4 - Billy Strings Fan Experience (Priority: P2)

A Billy Strings fan can access complete setlist data and engage with community features for the fast-growing bluegrass jam scene.

**Why this priority**: Billy Strings is the fastest-growing jam act, appealing to both bluegrass and jamband audiences.

**Independent Test**: User can browse all Billy Strings shows, view setlists, and rate performances.

**Acceptance Scenarios**:

1. **Given** Billy Strings data import, **When** user browses shows, **Then** they see shows from 2016-present
2. **Given** a BMFS show, **When** viewing setlist, **Then** user sees song titles, covers attributed to original artists

---

### Edge Cases

- What happens when a song is shared between multiple bands with different arrangements?
- How do we handle guest sit-ins across bands (e.g., Bobby Weir sitting in with Billy Strings)?
- How do we handle date conflicts (two bands playing same date)?
- What if a data source API becomes unavailable?

---

## Requirements

### Functional Requirements

- **FR-001**: System MUST support multiple "Verticals" (bands) with independent show/song data
- **FR-002**: System MUST allow users to track attendance across all bands from single account
- **FR-003**: System MUST import setlist data from band-specific APIs (Phish.net, Grateful Stats, etc.)
- **FR-004**: System MUST provide per-band navigation with clear visual distinction
- **FR-005**: System MUST display song gap statistics independently per band
- **FR-006**: System MUST allow performance ratings scoped to specific performances
- **FR-007**: System MUST support chase songs per band (user wants to see song X by band Y)
- **FR-008**: System SHOULD track cross-band song appearances where applicable
- **FR-009**: System SHOULD support band-specific theming/branding

### Key Entities

- **Vertical**: A band/artist (Goose, Phish, Grateful Dead, Dead & Company, Billy Strings)
- **Show**: A concert tied to a Vertical, Venue, and optional Tour
- **Song**: A composition tied to a Vertical (but may have cross-references)
- **Performance**: A specific play of a Song at a Show
- **User**: Single account spanning all Verticals
- **Attendance**: User's attendance at a Show
- **Rating/Review**: Tied to Performance, Show, or Song

---

## Success Criteria

### Measurable Outcomes

- **SC-001**: All target band data imported (500+ Phish shows, 2,000+ GD shows, 100+ D&C shows, 500+ BMFS shows)
- **SC-002**: Users can navigate between bands in <2 clicks
- **SC-003**: Search returns results across all bands in <500ms
- **SC-004**: Data import runs incrementally without duplicating existing records
- **SC-005**: Gap statistics calculate correctly per-band

---

## Data Source Specifications

### Phish.net API v5

- **Base URL**: `https://api.phish.net/v5`
- **Auth**: API key required (register at phish.net)
- **Endpoints**: `/shows`, `/setlists`, `/songs`, `/venues`
- **Rate Limit**: Unspecified, cache heavily
- **Attribution**: "Data courtesy of Phish.net"

### Grateful Stats API

- **Base URL**: `https://gratefulstats.com/api`
- **Auth**: TBD (may require key)
- **Coverage**: Grateful Dead complete, may include D&C
- **Attribution**: Required

### Setlist.fm API (Fallback)

- **Base URL**: `https://api.setlist.fm/rest/1.0`
- **Auth**: API key required
- **Coverage**: Universal, good for Billy Strings and D&C
- **Limitations**: Less structured than band-specific APIs

### Billy Strings Sources

- **bmfsdb.com**: Fan database, structure TBD
- **BillyBase (billybase.net)**: Alternative source
- **Fallback**: Setlist.fm

---

## Technical Approach

### Architecture Pattern

The existing elmeg-demo uses a `Vertical` model that already supports multi-band architecture:

```python
class Vertical(SQLModel, table=True):
    id: Optional[int]
    name: str          # "Phish"
    slug: str          # "phish"
    description: str
    
class Show(SQLModel, table=True):
    vertical_id: int   # Links to Vertical
    # ...

class Song(SQLModel, table=True):
    vertical_id: int   # Links to Vertical
    # ...
```

### Recommended Changes

1. **Data Import Layer**: Create pluggable importer classes per data source
2. **Frontend Routing**: Add `/{vertical}/` prefix to all routes
3. **API Scoping**: Add vertical filter to all list endpoints
4. **Theme System**: Per-vertical color/branding configuration