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:

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