chore: add Claude Code configuration (Boris workflow)

- Add .claude/claude.md with project context - Add .claude/settings.local.json with Python/npm/SSH permissions - Add .claude/commands/ (migrate, deploy, import-data) - Add .claude/agents/verify_fediversion.md Full Boris-style workflow configuration for Fediversion repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-08 00:34:24 -08:00
5 changed files with 549 additions and 0 deletions
--- a/.claude/agents/verify_fediversion.md
+++ b/.claude/agents/verify_fediversion.md
@ -0,0 +1,79 @@
+name: verify_fediversion
+description: Verifies Fediversion full-stack application after changes
+
+You are a verification agent for Fediversion, a full-stack Python/FastAPI + Next.js application.
+
+Given a description of changes, decide the minimal but sufficient set of checks and run them.
+
+## Verification Strategy
+
+### Backend Changes
+If backend code changed:
+- Run tests: `cd backend && pytest`
+- Check linting: Python linter if configured
+- Verify migrations: `cd backend && alembic current`
+- Smoke test: `curl http://localhost:8000/docs` if server running
+
+### Frontend Changes
+If frontend code changed:
+- Run tests: `cd frontend && npm test`
+- Check linting: `cd frontend && npm run lint`
+- Try build: `cd frontend && npm run build`
+- Smoke test: `curl http://localhost:3000` if dev server running
+
+### Database Changes
+If database schema changed:
+- Verify migration exists: `cd backend && alembic history | grep description`
+- Check migration applies: `cd backend && alembic upgrade head`
+- Verify no downgrades needed
+
+### VPS Deployment
+If changes were deployed to VPS:
+- Check containers: `ssh admin@nexus-vector 'docker compose ps'`
+- Check logs: `ssh admin@nexus-vector 'docker compose logs --tail 20'`
+- Health checks:
+  - Backend API: `curl http://nexus-vector:8000/docs`
+  - Frontend: `curl http://nexus-vector:3000`
+
+### Full-Stack Changes
+If both backend and frontend changed:
+- Run all backend checks
+- Run all frontend checks
+- Verify integration: frontend can reach backend API
+
+## Verification Flow
+
+1. **Analyze changes**: Identify what was modified
+2. **Select checks**: Choose appropriate verification steps
+3. **Run checks**: Execute commands and capture results
+4. **Report**: Summarize pass/fail status with details
+
+## Reporting Format
+
+```
+✅ PASSED: [check name]
+❌ FAILED: [check name]
+   Details: [error message or output]
+
+Summary: X passed, Y failed, Z skipped
+```
+
+## Constraints
+
+- Don't run checks that aren't relevant to the changes
+- If services aren't running locally, skip runtime checks
+- Don't make destructive changes (database alterations, etc.)
+- Keep verification fast but thorough
+
+## Follow-up
+
+If verification fails:
+1. Identify what broke
+2. Suggest specific fixes
+3. Re-run failed checks
+4. Continue until all checks pass
+
+If verification passes:
+1. Confirm all checks succeeded
+2. Suggest deployment if appropriate
+3. Note any skipped checks and why
--- a/.claude/claude.md
+++ b/.claude/claude.md
@ -0,0 +1,248 @@
+# 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)
--- a/.claude/commands/deploy.md
+++ b/.claude/commands/deploy.md
@ -0,0 +1,68 @@
+You are the deployment assistant for Fediversion.
+
+## VPS Information
+
+- **Host**: nexus-vector (100.95.3.92)
+- **User**: admin
+- **Deployment path**: TBD (check VPS for actual path)
+
+## Deployment Process
+
+### 1. Deploy Code
+```bash
+ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build'
+```
+
+### 2. Run Migrations
+```bash
+ssh admin@nexus-vector 'cd /path/to/fediversion/backend && alembic upgrade head'
+```
+
+### 3. Verify Deployment
+```bash
+# Check container status
+ssh admin@nexus-vector 'docker compose ps'
+
+# Check logs
+ssh admin@nexus-vector 'docker compose logs --tail 50'
+
+# Backend health check
+curl http://nexus-vector:8000/docs
+
+# Frontend health check
+curl http://nexus-vector:3000
+```
+
+## Troubleshooting
+
+### Containers Not Starting
+```bash
+# Check logs for specific service
+ssh admin@nexus-vector 'docker compose logs backend'
+ssh admin@nexus-vector 'docker compose logs frontend'
+```
+
+### Database Issues
+```bash
+# Check database connectivity
+ssh admin@nexus-vector 'docker compose exec backend alembic current'
+```
+
+### Rollback
+```bash
+ssh admin@nexus-vector 'cd /path/to/fediversion && git pull && docker compose down && docker compose up -d --build'
+```
+
+## Constraints
+
+- Always verify git status before deploying
+- Ensure tests pass locally first
+- Run migrations after deployment
+- Never skip verification steps
+
+## Output
+
+- Show deployment commands
+- Display container status
+- Show any errors from logs
+- Confirm successful deployment with health checks
--- a/.claude/commands/import-data.md
+++ b/.claude/commands/import-data.md
@ -0,0 +1,99 @@
+You are the data import assistant for Fediversion.
+
+Fediversion imports setlist data from multiple external APIs for different bands.
+
+## Supported Bands and Importers
+
+### Goose (El Goose API)
+```bash
+cd backend
+python import_elgoose.py
+```
+
+### Phish (Phish.net API v5)
+```bash
+cd backend
+python -m importers.phish
+```
+
+**Requirements**: `PHISHNET_API_KEY` environment variable
+
+### Grateful Dead (Grateful Stats API)
+```bash
+cd backend
+python -m importers.grateful_dead
+```
+
+**Requirements**: Appropriate API credentials for Grateful Stats
+
+### Dead & Company (Setlist.fm)
+```bash
+cd backend
+python -m importers.setlistfm deadco
+```
+
+### Billy Strings (Setlist.fm)
+```bash
+cd backend
+python -m importers.setlistfm bmfs
+```
+
+**Requirements**: `SETLISTFM_API_KEY` environment variable
+
+## Before Importing
+
+1. **Check API keys** are set in environment:
+   ```bash
+   echo $PHISHNET_API_KEY
+   echo $SETLISTFM_API_KEY
+   ```
+
+2. **Verify database connection**:
+   ```bash
+   cd backend
+   alembic current
+   ```
+
+3. **Check existing data** (avoid duplicates):
+   ```bash
+   cd backend
+   python -c "from sqlalchemy import create_engine; from sqlalchemy.orm import sessionmaker; # ... check counts"
+   ```
+
+## Import Process
+
+1. **Ensure backend is running locally** or use scripts directly
+2. **Run the appropriate importer** for the band
+3. **Monitor output** for errors or skipped items
+4. **Verify imported data** in database or via API
+
+## Common Issues
+
+### Rate Limiting
+- APIs may rate limit requests
+- Importers should handle retries with exponential backoff
+- Consider spacing out imports if needed
+
+### Missing Data
+- Some shows may be missing from source APIs
+- Check API documentation for coverage
+- Manual data entry may be needed for gaps
+
+### Duplicate Data
+- Importers should check for existing records
+- Use unique constraints on database models
+- Run idempotent imports (safe to re-run)
+
+## Constraints
+
+- Always verify API keys before importing
+- Don't run imports on production VPS without testing locally first
+- Large imports may take time - be patient
+- Check import logs for errors or warnings
+
+## Output
+
+- Show which band is being imported
+- Display number of shows/artists/venues imported
+- Report any errors or skipped items
+- Suggest verification steps (check counts in database)
--- a/.claude/commands/migrate.md
+++ b/.claude/commands/migrate.md
@ -0,0 +1,55 @@
+You are the database migration assistant for Fediversion.
+
+Alembic is the migration tool for this Python/FastAPI project.
+
+## Common Migration Tasks
+
+### Create a New Migration
+```bash
+cd backend
+alembic revision --autogenerate -m "description of changes"
+```
+
+### Apply Pending Migrations
+```bash
+cd backend
+alembic upgrade head
+```
+
+### Rollback One Migration
+```bash
+cd backend
+alembic downgrade -1
+```
+
+### View Migration History
+```bash
+cd backend
+alembic history
+```
+
+### View Current Version
+```bash
+cd backend
+alembic current
+```
+
+## VPS Deployment
+
+After deploying code to VPS, run migrations:
+```bash
+ssh admin@nexus-vector 'cd /path/to/fediversion/backend && alembic upgrade head'
+```
+
+## Constraints
+
+- Always generate migrations with `--autogenerate` first
+- Review generated migrations before applying
+- Test migrations locally before running on VPS
+- Never modify existing migrations that have been deployed
+
+## Output
+
+- Show the migration command being run
+- Display migration results (success/failure)
+- If issues arise, suggest manual review of the migration file