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

1. Modify models in `backend/models.py`
2. Generate migration:
   ```bash
   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:**
```bash
ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build'
```

**Run migrations:**
```bash
ssh admin@nexus-vector 'cd /path/to/fediversion/backend && alembic upgrade head'
```

**Verify:**
```bash
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:**
```bash
cd backend
python import_elgoose.py
```

**Import Phish data:**
```bash
cd backend
python -m importers.phish
```

**Import from Setlist.fm (D&C, Billy Strings):**
```bash
cd backend
python -m importers.setlistfm deadco
python -m importers.setlistfm bmfs
```

## 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`
- 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)