---
description: fediversion development environment and workflow requirements
---

# Fediversion Development Workflow

## CRITICAL: Development Environment

**All development and testing happens on nexus-vector.** Do NOT use local SQLite for dev/testing.

### Why nexus-vector?

- Production-like PostgreSQL database
- All imported band data lives there (10,605+ shows, 139k+ performances)
- Proper Docker environment matching production
- Local SQLite is stale/empty and should NOT be used

### Development Servers

| Environment | Server | Path | URL |
|-------------|--------|------|-----|
| **Staging** | nexus-vector | `/srv/containers/fediversion` | fediversion.runfoo.run |
| **Production** | tangible-aacorn | `/srv/containers/fediversion` | (domain TBD) |

---

## SSH Access

```bash
# Connect to staging dev environment
ssh nexus-vector

# Navigate to project
cd /srv/containers/fediversion
```

---

## Database

### Query Data

```bash
# On nexus-vector
docker compose exec db psql -U fediversion -d fediversion
```

### Check Band Data

```bash
docker compose exec db psql -U fediversion -d fediversion -c "
SELECT v.name, COUNT(s.id) as shows 
FROM vertical v 
LEFT JOIN show s ON s.vertical_id = v.id 
GROUP BY v.id 
ORDER BY shows DESC;"
```

---

## Running Importers

Importers run inside the backend container to access the PostgreSQL database:

```bash
# On nexus-vector
docker compose exec backend python -m importers.setlistfm deadco
docker compose exec backend python -m importers.setlistfm bmfs
docker compose exec backend python -m importers.phish
docker compose exec backend python -m importers.grateful_dead
```

### API Keys

Importers require API keys set in `.env`:

- `SETLISTFM_API_KEY` - For Dead & Co, Billy Strings, JRAD, Eggy, etc.
- `PHISHNET_API_KEY` - For Phish data
- `GRATEFULSTATS_API_KEY` - For Grateful Dead (may not be required)

---

## Cache

API responses are cached in `backend/importers/.cache/` (4,800+ files).

- Cache TTL: 1 hour
- Cache persists across runs
- Re-import uses cache first → no API calls wasted

---

## Imported Band Data (Dec 2025)

| Band | Shows | Performances |
|------|-------|--------------|
| DSO | 4,414 | 65,172 |
| SCI | 1,916 | 27,225 |
| Disco Biscuits | 1,860 | 19,935 |
| Phish | 4,266 | (in progress) |
| MSI | 758 | 9,501 |
| Eggy | 666 | 4,705 |
| Dogs in a Pile | 601 | 7,558 |
| JRAD | 390 | 5,452 |

### Still Need Import

- Goose (El Goose API)
- Grateful Dead (Grateful Stats API)
- Dead & Company (Setlist.fm)
- Billy Strings (Setlist.fm)