fediversion/.claude/claude.md

# Project Overview

**Name**: Fediversion
**Type**: Full-stack application (Python backend + Next.js frontend)
**Purpose**: The ultimate HeadyVersion platform for ALL jam bands
**Primary Languages**: Python (FastAPI), TypeScript (Next.js 16)

## High-Level Description

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

**Supported Bands:**
- 🦆 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

## Layout

```
fediversion/
├── backend/                   # Python FastAPI backend
│   ├── main.py               # FastAPI app entry point
│   ├── models/               # SQLModel database models
│   ├── routers/              # API route handlers
│   ├── services/             # Business logic
│   └── alembic/              # Database migrations
├── frontend/                  # Next.js 16 frontend
│   ├── app/                  # Next.js App Router
│   ├── components/           # React components
│   └── lib/                  # Utilities and API client
├── email/                     # Email templates
├── docs/                      # Documentation
├── docker-compose.yml         # Local development stack
└── database.db                # SQLite database (dev)
```

## Conventions

### Backend (Python)
- **Framework**: FastAPI with uvicorn server
- **ORM**: SQLModel (built on SQLAlchemy + Pydantic)
- **Migrations**: Alembic
- **Auth**: JWT tokens (python-jose), bcrypt hashing
- **Validation**: Pydantic models
- **Testing**: pytest

### Frontend (Next.js)
- **Version**: Next.js 16 with App Router
- **React**: Version 19
- **Styling**: Tailwind CSS v4
- **Components**: Radix UI primitives
- **State**: React hooks, server components
- **Testing**: Jest + Testing Library

### Database
- **Development**: SQLite (`database.db`)
- **Production**: PostgreSQL
- **Migrations**: Alembic in `backend/alembic/`

### Error Handling
- Backend: Return proper HTTP status codes with error messages
- Frontend: Display user-friendly error messages
- Never expose sensitive data (API keys, passwords)

## Patterns & Playbooks

### How to Run Locally

**Backend (port 8000):**
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```

**Frontend (port 3000):**
```bash
cd frontend
npm install
npm run dev
```

**Full stack (Docker):**
```bash
docker compose up -d
```

### How to Run Database Migrations

**Create new migration:**
```bash
cd backend
alembic revision --autogenerate -m "description"
```

**Apply migrations:**
```bash
cd backend
alembic upgrade head
```

**Rollback migration:**
```bash
cd backend
alembic downgrade -1
```

### How to Import Band Data

Set API keys and run import:
```bash
export PHISHNET_API_KEY="your-key"
export SETLISTFM_API_KEY="your-key"

# Run import scripts (check backend/services/ for import scripts)
python -m backend.services.import_phish
python -m backend.services.import_goose
```

### How to Add New Band Support

1. Identify data source (API, scraping, etc.)
2. Create import service in `backend/services/import_[band].py`
3. Add models if needed
4. Create API routes in `backend/routers/`
5. Add frontend components to display band data
6. Add tests for import logic

### VPS Deployment (nexus-vector)

**Deploy to VPS:**
```bash
# SSH to nexus-vector
ssh admin@nexus-vector

# Navigate to project
cd /path/to/fediversion

# Pull latest changes
git pull

# Restart services
docker compose down && docker compose up -d --build
```

**Or automate:**
```bash
ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build'
```

## Important Environment Variables

### Backend
- `DATABASE_URL`: Database connection string (SQLite or PostgreSQL)
- `SECRET_KEY`: JWT secret key
- `PHISHNET_API_KEY`: Phish.net API key
- `SETLISTFM_API_KEY`: Setlist.fm API key
- `GRATEFUL_STATS_API_KEY`: Grateful Stats API key (if applicable)

### Frontend
- `NEXT_PUBLIC_API_URL`: Backend API URL

## Testing Strategy

- **Backend tests**: pytest with test database
- **Frontend tests**: Jest + Testing Library
- **E2E tests**: Playwright for critical flows (view shows, rate shows)
- **API tests**: Test CRUD operations for shows, songs, ratings

## Data Source Integration

### Current Integrations
- **Goose**: El Goose API (proprietary)
- **Phish**: Phish.net API v5 ( documented at phish.net/api)
- **Grateful Dead**: Grateful Stats API
- **Dead & Company**: Setlist.fm
- **Billy Strings**: Setlist.fm

### Integration Patterns
1. Fetch data from external API
2. Transform to internal data models
3. Store in database (backend/models/)
4. Expose via API endpoints (backend/routers/)
5. Display in frontend (frontend/app/)

## PR & Learning Workflow

- When a PR introduces a new pattern or fixes a subtle issue:
  1. Summarize the lesson in 1-2 bullets
  2. Append under "Patterns & Playbooks" above
  3. Consider updating relevant documentation in `docs/`

## Multi-Band Architecture

### Band-Agnostic Design
- Core models (Show, Song, Venue) are band-agnostic
- Band-specific data stored in band_* tables
- API endpoints support `?band=goose|phish|dead` filtering
- Frontend adapts UI based on selected band

### User Accounts
- Single account supports all bands
- Ratings and favorites are per-user, per-band
- Unified activity feed across all bands