# Fediversion

**The ultimate HeadyVersion platform for ALL jam bands.**

Fediversion is a unified setlist tracking, rating, and community platform supporting multiple jam bands from a single account.

## Supported Bands

| Band | Data Source | Status |
|------|-------------|--------|
| 🦆 Goose | El Goose API | ✅ Active |
| 🐟 Phish | Phish.net API v5 | 🔄 Ready |
| 💀 Grateful Dead | Grateful Stats API | 🔄 Ready |
| ⚡ Dead & Company | Setlist.fm | 🔄 Ready |
| 🎸 Billy Strings | Setlist.fm | 🔄 Ready |

## Quick Start

### Prerequisites

- Python 3.11+
- Node.js 18+
- PostgreSQL (optional, SQLite works for dev)

### 1. Backend (Port 8000)

```bash
cd backend
pip install -r requirements.txt

# Set API keys for data import (optional)
export PHISHNET_API_KEY="your-key"
export SETLISTFM_API_KEY="your-key"

# Run migrations
alembic upgrade head

# Start server
uvicorn main:app --reload --port 8000
```

### 2. Frontend (Port 3000)

```bash
cd frontend
npm install
npm run dev
```

### 3. Import Band Data

```bash
cd backend

# Import Goose (existing)
python import_elgoose.py

# Import Phish
python -m importers.phish

# Import Grateful Dead
python -m importers.grateful_dead

# Import Dead & Company
python -m importers.setlistfm deadco

# Import Billy Strings
python -m importers.setlistfm bmfs
```

## API Keys

| Service | Get Key At | Required For |
|---------|------------|--------------|
| Phish.net | <https://phish.net/api> | Phish data |
| Setlist.fm | <https://api.setlist.fm> | D&C, Billy Strings |
| Grateful Stats | <https://gratefulstats.com> | Grateful Dead |

## Git Repository

**Repo**: <https://git.runfoo.run/runfoo-org/fediversion>

### Push via Tailscale

SSH port 2222 blocked externally. Use Tailscale IP for nexus-vector:

```bash
# Set remote to Tailscale IP (nexus-vector = 100.95.3.92)
git remote set-url origin ssh://git@100.95.3.92:2222/runfoo-org/fediversion.git

# Push
git push origin main
git push origin testing  # Triggers CI/CD deploy to fediversion.runfoo.run
```

### CI/CD Branches

| Branch | Server | URL |
|--------|--------|-----|
| `testing` | nexus-vector | fediversion.runfoo.run |
| `production` | tangible-aacorn | (when domain ready) |

## Architecture

```
fediversion/
├── backend/
│   ├── importers/           # Band-specific data importers
│   │   ├── base.py          # Abstract base class
│   │   ├── phish.py         # Phish.net API
│   │   ├── grateful_dead.py # Grateful Stats API
│   │   └── setlistfm.py     # D&C, Billy Strings
│   ├── routers/             # API endpoints
│   ├── models.py            # SQLModel database models
│   └── main.py              # FastAPI app
├── frontend/
│   ├── app/                 # Next.js 14 app router
│   └── components/          # React components
└── docker-compose.yml
```

## Core Concept: Verticals

Fediversion uses the "Vertical" model to support multiple bands:

```python
class Vertical(SQLModel):
    name: str       # "Phish"
    slug: str       # "phish"
    description: str

class Show(SQLModel):
    vertical_id: int  # Links to band
    # ...
```

Routes support both single-band (`/shows`) and multi-band (`/phish/shows`) patterns.

## Based On

Fediversion is forked from [elmeg-demo](https://git.runfoo.run/runfoo-org/elmeg-demo) (elmeg.xyz), the Goose setlist platform.

## License

MIT