fediversion/.claude/claude.md

Project Overview

Name: Fediversion Type: Full-stack web application (Python FastAPI + Next.js) Primary Languages: Python (backend), TypeScript (frontend) Status: Active development

High-Level Description

Fediversion is a unified setlist tracking, rating, and community platform for jam bands. It supports multiple bands (Goose, Phish, Grateful Dead, Dead & Company, Billy Strings) from a single account using a "vertical" architecture.

Architecture:

Frontend (Next.js 16) → Backend (FastAPI) → Database (PostgreSQL/SQLite)
                      ↓
                 Data Importers (Phish.net, Setlist.fm, Grateful Stats)

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/                  # FastAPI 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
│   ├── alembic/             # Database migrations
│   └── main.py              # FastAPI app entry
├── frontend/                 # Next.js 16 frontend
│   ├── app/                 # App router
│   ├── components/          # React components
│   └── package.json
├── docs/                     # Documentation
├── email/                    # Email templates
├── docker-compose.yml        # Local development
└── DEPLOY.md                 # Deployment guide

Conventions

Language/Style

• Backend: Python 3.11+, FastAPI, SQLModel, Alembic
• Frontend: Next.js 16, React 19, Radix UI, Tailwind CSS
• TypeScript strict mode enabled
• Conventional commits for git messages

Package Managers

• Backend: pip for Python dependencies
• Frontend: npm for Node.js dependencies

Database (Alembic)

• Migrations in backend/alembic/
• Create migration: alembic revision --autogenerate -m "description"
• Apply migrations: alembic upgrade head
• Downgrade: alembic downgrade -1

Error Handling

• Backend: FastAPI exception handlers
• Frontend: Error boundaries and proper toast notifications
• Never expose sensitive data in error messages

Logging

• Backend: Python logging module
• Frontend: Console in dev, structured logging in prod

Config

• Backend: Environment variables via python-dotenv
• Frontend: Next.js env vars (NEXT_PUBLIC_*)
• Never hard-code secrets or API keys

Patterns & Playbooks

How to Run Locally

Backend (port 8000):

cd backend
pip install -r requirements.txt
alembic upgrade head
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 Write Database Migrations

1. Modify models in backend/models.py
2. Generate migration:

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

3. Review migration in backend/alembic/versions/
4. Apply migration: alembic upgrade head

How to Add a New Band Importer

1. Create importer in backend/importers/{band}.py
2. Inherit from BaseImporter class
3. Implement required methods: fetch_shows, parse_show, etc.
4. Add entry point to __main__.py or create standalone script
5. Test with: python -m importers.{band}

How to Add API Endpoints

1. Create router in backend/routers/
2. Use FastAPI decorators: @router.get("/path")
3. Register in backend/main.py: app.include_router(router)
4. Add request/response models with SQLModel or Pydantic
5. Add error handling for edge cases

How to Add Frontend Components

1. Create component in frontend/components/
2. Use Radix UI primitives + Tailwind styling
3. Follow existing patterns (class-variance-authority, clsx)
4. Export from component index file if needed
5. Use Next.js app router for pages

VPS Deployment (nexus-vector)

Deploy to VPS:

ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build'

Run migrations:

ssh admin@nexus-vector 'cd /path/to/fediversion/backend && alembic upgrade head'

Verify:

ssh admin@nexus-vector 'docker compose ps'
ssh admin@nexus-vector 'docker compose logs --tail 50'

Important Environment Variables

Backend

• DATABASE_URL: PostgreSQL/SQLite connection string
• SECRET_KEY: JWT secret for authentication
• PHISHNET_API_KEY: Phish.net API access
• SETLISTFM_API_KEY: Setlist.fm API access

Frontend

• NEXT_PUBLIC_API_URL: Backend API URL
• NEXT_PUBLIC_APP_URL: Frontend URL

Data Import

Import Goose data:

cd backend
python import_elgoose.py

Import Phish data:

cd backend
python -m importers.phish

Import from Setlist.fm (D&C, Billy Strings):

cd backend
python -m importers.setlistfm deadco
python -m importers.setlistfm bmfs

Core Concept: Verticals

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

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
• Multi-band: /phish/shows

Testing Strategy

• Backend: pytest with httpx for API tests
• Frontend: Jest for component tests
• E2E: Manual testing of critical flows
• Build verification: Both backend and frontend must build successfully

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 Considerations

Data Source Integration

• Each band has a different API (Phish.net, Setlist.fm, Grateful Stats)
• Importers abstract away API differences
• All data normalizes to common models (Show, Song, Venue, etc.)

Route Patterns

• Global routes: /shows, /venues, /songs (all bands)
• Vertical-specific routes: /phish/shows, /dead/venues (single band)
• Frontend handles both patterns with dynamic routing

Performance

• Database indexes on vertical_id for efficient filtering
• API response caching for frequently accessed data
• Importers run asynchronously via background tasks

Deployment Notes

• VPS: nexus-vector (100.95.3.92)
• User: admin
• Database: PostgreSQL in production, SQLite for local dev
• Reverse Proxy: Traefik (configured in traefik-routes.yml)
• Containers: backend, frontend, db (PostgreSQL)