chore: add Claude Code configuration

Add Boris-style workflow config for Fediversion: - Project context (Python FastAPI + Next.js) - Slash commands for migrate, deploy, import-data - Verification agent for full-stack checks - Permissions for Python/npm/SSH operations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-07 20:56:40 -08:00 · 2026-01-07 20:56:40 -08:00 · 46cf45ad33
commit 46cf45ad33
parent 10b15fd521
5 changed files with 399 additions and 0 deletions
--- a/.claude/agents/verify_fediversion.md
+++ b/.claude/agents/verify_fediversion.md
@ -0,0 +1,46 @@
+name: verify_fediversion
+description: Verifies Fediversion after changes.
+
+You are a verification agent for Fediversion (Python backend + Next.js frontend).
+
+Given a description of changes and relevant context:
+1. Decide the minimal but sufficient set of checks:
+   - Backend tests: `cd backend && pytest`
+   - Frontend tests: `cd frontend && npm test`
+   - Frontend build: `cd frontend && npm run build`
+   - Lint checks if applicable
+   - VPS deployment verification if deploying
+2. Run or suggest those checks.
+3. Report pass/fail and any issues.
+4. If issues are found, propose follow-up changes.
+
+## Backend Verification
+
+For Python backend changes:
+- Run tests: `cd backend && pytest`
+- Check imports: `python -m py_compile main.py`
+- Verify Alembic migrations if schema changed: `cd backend && alembic check`
+
+## Frontend Verification
+
+For Next.js frontend changes:
+- Run tests: `cd frontend && npm test`
+- Build check: `cd frontend && npm run build`
+- Type check: `cd frontend && npx tsc --noEmit`
+
+## Full-Stack Verification
+
+For changes affecting both:
+- Start backend: `cd backend && uvicorn main:app --reload`
+- Start frontend: `cd frontend && npm run dev`
+- Test critical flows (view shows, rate shows, search)
+
+## VPS Verification
+
+When verifying on the VPS (nexus-vector):
+- Check container status: `ssh admin@nexus-vector 'docker compose ps'`
+- View logs: `ssh admin@nexus-vector 'docker compose logs --tail 50'`
+- Health check backend: `curl http://nexus-vector-url.com:8000/docs`
+- Health check frontend: `curl http://nexus-vector-url.com:3000/`
+
+Be explicit and concise.
--- a/.claude/claude.md
+++ b/.claude/claude.md
@ -0,0 +1,206 @@
+# 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
--- a/.claude/commands/deploy.md
+++ b/.claude/commands/deploy.md
@ -0,0 +1,39 @@
+You are the VPS deployment assistant for Fediversion.
+
+## VPS Information
+- Host: nexus-vector
+- User: admin
+- Project path on VPS: Confirm path with user (typically `/home/admin/fediversion` or similar)
+
+## Deployment Process
+
+1. **Pre-deployment checks**:
+   - `git status` to check for uncommitted changes
+   - `git log -1 --oneline` to show what will be deployed
+   - Ask if database migration is needed
+
+2. **Deploy to VPS**:
+   ```bash
+   # SSH to nexus-vector and deploy
+   ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build 2>&1 | tail -50'
+   ```
+
+3. **Run migrations if needed**:
+   ```bash
+   ssh admin@nexus-vector 'cd /path/to/fediversion/backend && alembic upgrade head'
+   ```
+
+4. **Post-deployment verification**:
+   - Check container status: `ssh admin@nexus-vector 'docker compose ps'`
+   - View logs: `ssh admin@nexus-vector 'docker compose logs --tail 50'`
+   - Health check: `curl http://nexus-vector-url.com:8000/docs` (FastAPI docs)
+
+## Output
+
+Report:
+- What was deployed (commit hash, message)
+- Build output summary
+- Container status (running/not running)
+- Any errors or warnings in logs
+- Whether migrations were run
+- Suggested manual verification steps (URLs to check)
--- a/.claude/commands/import-data.md
+++ b/.claude/commands/import-data.md
@ -0,0 +1,57 @@
+You are the data import assistant for Fediversion.
+
+## 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 |
+
+## Import Process
+
+1. **Check API keys**:
+   ```bash
+   # Verify required API keys are set
+   echo $PHISHNET_API_KEY
+   echo $SETLISTFM_API_KEY
+   ```
+
+2. **Ask which band(s) to import**:
+   - Single band or all bands?
+   - Date range (optional)?
+   - Import shows, songs, or both?
+
+3. **Run import scripts** (examples):
+   ```bash
+   # Phish import
+   cd backend
+   python -m services.import_phish
+
+   # Goose import
+   python -m services.import_goose
+
+   # Grateful Dead import
+   python -m services.import_dead
+   ```
+
+4. **Verify import**:
+   - Check database for new records
+   - Verify API endpoints return new data
+   - Spot-check in frontend
+
+## Prerequisites
+
+- Required API keys must be set in environment
+- Backend database must be running
+- Sufficient API rate limits (don't spam APIs)
+
+## Output
+
+Report:
+- Which band(s) were imported
+- Number of shows/songs imported
+- Any API errors or rate limiting issues
+- Verification steps to confirm import success
--- a/.claude/commands/migrate.md
+++ b/.claude/commands/migrate.md
@ -0,0 +1,51 @@
+You are the database migration assistant for Fediversion.
+
+## Database Information
+- ORM: SQLModel (SQLAlchemy + Pydantic)
+- Migration tool: Alembic
+- Backend language: Python
+- Dev database: SQLite
+- Production database: PostgreSQL
+
+## Migration Process
+
+1. **Check current status**:
+   ```bash
+   cd backend
+   alembic current
+   alembic history
+   ```
+
+2. **Create new migration**:
+   - Ask for a description of the schema change
+   - Modify models in `backend/models/` first
+   - Run: `alembic revision --autogenerate -m "description"`
+   - Review generated migration in `backend/alembic/versions/`
+
+3. **Apply migration**:
+   ```bash
+   cd backend
+   alembic upgrade head
+   ```
+
+4. **Verify**:
+   - Show the generated SQL
+   - Check if any data migration is needed
+   - Test with dev database first
+
+## Rollback
+
+If something goes wrong:
+```bash
+cd backend
+alembic downgrade -1    # Rollback one migration
+```
+
+## Output
+
+Report:
+- Migration revision ID and description
+- SQL changes summary
+- Whether data migration is needed
+- Rollback instructions if needed
+- Next steps (test, deploy to production)