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):

cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend (port 3000):

cd frontend
npm install
npm run dev

Full stack (Docker):

docker compose up -d

How to Run Database Migrations

Create new migration:

cd backend
alembic revision --autogenerate -m "description"

Apply migrations:

cd backend
alembic upgrade head

Rollback migration:

cd backend
alembic downgrade -1

How to Import Band Data

Set API keys and run import:

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:

# 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:

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