deploy to Fly.io and prepare frontend for Vercel

- backend: deployed to Fly.io at relay-api.fly.dev
- frontend: configured API_URL for environment-based backend URL
- removed Cloudflare-specific configs (wrangler.toml, adapter-cloudflare)
- added Dockerfile with git support for atproto fork
- added fly.toml with secrets and R2 config

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

.dockerignore

···
+.git
+.github
+.venv
+.venv-workers
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.coverage
+htmlcov
+dist
+build
+*.egg-info
+.env
+.env.local
+data/
+frontend/
+sandbox/
+tests/
+docs/
+*.md
+!README.md

.env.example

···
 # redis
 REDIS_URL=redis://localhost:6379/0
 
-# cloudflare r2
-R2_ACCOUNT_ID=
-R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
-R2_BUCKET_NAME=relay-audio
+# storage
+STORAGE_BACKEND=filesystem  # or "r2"
+
+# cloudflare r2 (only needed if STORAGE_BACKEND=r2)
+AWS_ACCESS_KEY_ID=your_r2_access_key_id
+AWS_SECRET_ACCESS_KEY=your_r2_secret_access_key
+R2_BUCKET=relay-audio
+R2_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
+R2_PUBLIC_BUCKET_URL=https://audio.relay.example.com
 
 # atproto
 ATPROTO_PDS_URL=https://bsky.social

CLAUDE.md

···
 
 - **testing**: empirical first - run code and prove it works before writing tests
 - **auth**: OAuth 2.1 implementation from fork (`git+https://github.com/zzstoatzz/atproto@main`)
-- **storage**: filesystem for MVP, will migrate to R2 later
-- **database**: delete `data/relay.db` when Track model changes (no migrations yet)
-- **frontend**: SvelteKit with **bun** (not npm/pnpm) - reference project in `sandbox/huggingchat-ui` for patterns
-- **justfile**: use `just` for dev workflows when needed
+- **storage**: Cloudflare R2 for audio files
+- **database**: Neon PostgreSQL (serverless)
+- **frontend**: SvelteKit with **bun** (not npm/pnpm)
+- **backend**: FastAPI deployed on Fly.io
+- **deployment**: `flyctl deploy` (runs in background per user prefs)

Dockerfile

···
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+# install git for git dependencies
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# install dependencies
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+# copy application code
+COPY . .
+
+# install the project itself
+RUN uv sync --frozen --no-dev
+
+# expose port
+EXPOSE 8000
+
+# run the application
+CMD ["uv", "run", "uvicorn", "relay.main:app", "--host", "0.0.0.0", "--port", "8000"]

docs/README.md

···
+# relay ATProto integration documentation
+
+this directory contains the complete plan and implementation guides for integrating relay with ATProto.
+
+## documents
+
+### [`atproto-integration-plan.md`](./atproto-integration-plan.md)
+
+**overview document** - read this first to understand the overall architecture and approach.
+
+covers:
+- hybrid storage model (R2 + ATProto records)
+- lexicon design for `app.relay.track`
+- implementation phases
+- data flow diagrams
+- open questions and decisions
+
+### [`phase1-r2-implementation.md`](./phase1-r2-implementation.md)
+
+**R2 storage migration** - practical guide to moving from filesystem to cloudflare R2.
+
+covers:
+- R2 bucket setup and configuration
+- implementation of `R2Storage` class
+- migration strategies
+- testing procedures
+- cost estimates (~$0.16/month for 1000 tracks)
+
+### [`phase2-atproto-records.md`](./phase2-atproto-records.md)
+
+**ATProto record creation** - guide to writing track metadata to user's PDS.
+
+covers:
+- database schema updates
+- `create_track_record()` implementation
+- upload endpoint modifications
+- error handling strategies
+- frontend integration
+
+## quick start
+
+### current state (MVP)
+
+relay is working with:
+- ✅ OAuth 2.1 authentication (ATProto)
+- ✅ filesystem storage for audio files
+- ✅ track upload and playback
+- ✅ basic music player
+
+### next steps
+
+#### immediate (phase 1)
+
+migrate audio storage to R2:
+
+1. set up R2 bucket in cloudflare
+2. add credentials to `.env`
+3. implement `R2Storage` class (see phase1 doc)
+4. set `STORAGE_BACKEND=r2`
+5. test upload and playback
+
+**estimated effort**: 2-3 hours
+
+#### near-term (phase 2)
+
+add ATProto record creation:
+
+1. update Track model with ATProto fields
+2. create `atproto/records.py` module
+3. modify upload endpoint to create records
+4. test record creation on personal PDS
+5. update frontend to show "published to ATProto" badge
+
+**estimated effort**: 3-4 hours
+
+#### future (phase 3)
+
+implement discovery via firehose:
+
+1. set up jetstream consumer
+2. listen for `app.relay.track` commits
+3. index discovered tracks
+4. add discovery feed to frontend
+
+**estimated effort**: 8-12 hours (deferred)
+
+## architecture decisions
+
+### why R2 instead of PDS blobs?
+
+PDS blobs are designed for smaller files like images. audio files are:
+- larger (5-50MB per track)
+- require streaming
+- benefit from CDN distribution
+
+R2 provides:
+- scalable storage
+- free egress to cloudflare CDN
+- simple HTTP URLs
+- cost-effective (~$0.015/GB/month)
+
+### why unofficial lexicon?
+
+relay uses `app.relay.track` as an unofficial lexicon (similar to `app.at-me.visit`) because:
+- faster iteration during development
+- no formal governance needed for MVP
+- can migrate to official lexicon later if needed
+
+### why hybrid storage?
+
+storing metadata on ATProto provides:
+- user data sovereignty (users own their catalog)
+- decentralization (no single point of failure)
+- portability (users can move to another client)
+
+storing audio on R2 provides:
+- performance (fast streaming)
+- scalability (handles growth)
+- cost efficiency (cheaper than PDS blobs)
+
+## testing strategy
+
+### phase 1 testing
+
+```bash
+# 1. upload test file
+curl -X POST http://localhost:8001/tracks/ \
+  -H "Cookie: session_id=..." \
+  -F "file=@test.mp3" \
+  -F "title=test" \
+  -F "artist=test"
+
+# 2. verify R2 storage
+# check cloudflare dashboard for file
+
+# 3. test playback
+# open frontend and play track
+```
+
+### phase 2 testing
+
+```bash
+# 1. upload and check record
+curl -X POST http://localhost:8001/tracks/ ...
+# response should include atproto_record_uri
+
+# 2. verify on PDS
+# use at-me or similar tool to view records
+
+# 3. check record content
+python scripts/check_record.py <record_uri>
+```
+
+## troubleshooting
+
+### R2 upload fails
+
+```
+error: failed to upload to R2
+```
+
+**check**:
+- R2 credentials in `.env`
+- bucket exists and is accessible
+- account ID is correct
+
+### ATProto record creation fails
+
+```
+error: failed to create atproto record
+```
+
+**check**:
+- OAuth session is valid (not expired)
+- user has write permissions
+- PDS is accessible
+- record format is valid
+
+### audio won't play
+
+```
+404: audio file not found
+```
+
+**check**:
+- `STORAGE_BACKEND` matches actual storage
+- R2 bucket has public read access
+- file_id matches database record
+
+## monitoring
+
+### key metrics to track
+
+1. **upload success rate**
+   - total uploads attempted
+   - successful R2 uploads
+   - successful record creations
+
+2. **storage costs**
+   - total R2 storage (GB)
+   - monthly operations count
+   - estimated cost
+
+3. **playback metrics**
+   - tracks played
+   - average stream duration
+   - errors/failures
+
+### logging
+
+add structured logging for debugging:
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+logger.info(
+    "track_uploaded",
+    track_id=track.id,
+    r2_url=r2_url,
+    atproto_uri=atproto_uri,
+)
+```
+
+## security considerations
+
+### audio file access
+
+**current**: R2 URLs are public (anyone with URL can access)
+
+**acceptable for MVP** because:
+- music is meant to be shared
+- no sensitive content
+- URL guessing is impractical (content-based hashes)
+
+**future enhancement**: signed URLs with expiration
+
+### record ownership
+
+**enforced by ATProto**: only user with valid OAuth session can create records in their repo
+
+**enforced by relay**: tracks are associated with `artist_did` and only owner can delete
+
+### rate limiting
+
+**recommended**: limit uploads to prevent abuse
+- 10 uploads per hour per user
+- 100MB total per hour per user
+
+## cost projections
+
+### 1000 tracks (typical small catalog)
+
+- storage: 10GB @ $0.015/GB = $0.15/month
+- uploads: 1000 operations @ $4.50/million = $0.005
+- streams: 10k plays @ $0.36/million = $0.004
+- **total: ~$0.16/month**
+
+### 10,000 tracks (medium platform)
+
+- storage: 100GB @ $0.015/GB = $1.50/month
+- uploads: 10k operations = $0.045
+- streams: 100k plays = $0.036
+- **total: ~$1.58/month**
+
+### 100,000 tracks (large platform)
+
+- storage: 1TB @ $0.015/GB = $15/month
+- uploads: 100k operations = $0.45
+- streams: 1M plays = $0.36
+- **total: ~$15.81/month**
+
+**note**: these are R2 costs only. add compute, database, etc.
+
+## references
+
+### ATProto documentation
+
+- [repository spec](https://atproto.com/specs/repository)
+- [lexicon spec](https://atproto.com/specs/lexicon)
+- [data model](https://atproto.com/specs/data-model)
+- [OAuth 2.1](https://atproto.com/specs/oauth)
+
+### cloudflare documentation
+
+- [R2 overview](https://developers.cloudflare.com/r2/)
+- [R2 pricing](https://developers.cloudflare.com/r2/pricing/)
+- [S3 compatibility](https://developers.cloudflare.com/r2/api/s3/)
+
+### relay project files
+
+- current status: `sandbox/status-2025-10-28.md`
+- project instructions: `CLAUDE.md`
+- atproto fork: `sandbox/atproto-fork/`
+- example projects: `sandbox/at-me/`, `sandbox/status/`
+
+## contributing
+
+when implementing these plans:
+
+1. **test empirically first** - run code and prove it works
+2. **reference existing docs** - check sandbox directory before researching
+3. **keep it simple** - MVP over perfection
+4. **use lowercase** - respect relay's aesthetic
+5. **no sprawl** - avoid creating multiple versions of files
+
+## questions?
+
+if anything is unclear:
+- check the relevant phase document
+- review example projects in sandbox
+- consult ATProto official docs
+- look at your atproto fork implementation

docs/atproto-integration-plan.md

···
+# atproto integration plan for relay
+
+## architecture summary
+
+relay uses a **hybrid storage model**:
+- **audio files**: stored on cloudflare R2 (not PDS blobs)
+- **track metadata**: stored as ATProto records on user's PDS
+- **records contain**: R2 URLs pointing to audio files
+
+this approach provides:
+- user data sovereignty (metadata lives in user's PDS)
+- scalable storage (R2 for large audio files)
+- decentralized identity (ATProto DIDs)
+- portability (users own their track metadata)
+
+## lexicon design
+
+### `app.relay.track`
+
+**namespace rationale**: using `app.relay.*` because relay is hosted as an application, not under a controlled domain. this is an unofficial, experimental lexicon similar to `app.at-me.visit`.
+
+**record structure**:
+```json
+{
+  "$type": "app.relay.track",
+  "title": "song title",
+  "artist": "artist name",
+  "album": "optional album name",
+  "audioUrl": "https://relay-audio.r2.dev/abc123.mp3",
+  "fileType": "mp3",
+  "duration": 240,
+  "createdAt": "2025-10-28T22:30:00Z"
+}
+```
+
+**field definitions**:
+- `$type` (required): `app.relay.track`
+- `title` (required): string, max 280 chars
+- `artist` (required): string, max 280 chars
+- `album` (optional): string, max 280 chars
+- `audioUrl` (required): https URL to R2-hosted audio file
+- `fileType` (required): string, one of: `mp3`, `wav`, `ogg`, `flac`
+- `duration` (optional): integer, seconds
+- `createdAt` (required): ISO 8601 timestamp
+
+**record key**: use TID (Timestamp Identifier) for chronological ordering
+
+## implementation phases
+
+### phase 1: R2 storage migration (current priority)
+
+**goal**: migrate from filesystem to cloudflare R2
+
+**tasks**:
+1. set up cloudflare R2 bucket and credentials
+2. create R2 storage adapter in `src/relay/storage.py`
+3. update `upload_track` endpoint to use R2
+4. update audio serving endpoint to proxy from R2
+5. migrate existing local files to R2
+
+**configuration** (in `.env`):
+```bash
+# cloudflare R2
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET_NAME=relay-audio
+R2_PUBLIC_URL=https://relay-audio.r2.dev
+```
+
+### phase 2: ATProto record creation
+
+**goal**: write track metadata to user's PDS when uploading
+
+**tasks**:
+1. create `src/relay/atproto/records.py` module
+2. implement `create_track_record()` function using existing OAuth client
+3. update `upload_track` endpoint to:
+   - upload audio to R2 (get URL)
+   - create ATProto record with R2 URL
+   - store local Track model for fast querying
+4. handle record creation errors gracefully
+
+**code structure**:
+```python
+# src/relay/atproto/records.py
+from atproto import Client
+from relay.auth import get_oauth_session
+
+async def create_track_record(
+    auth_session: Session,
+    title: str,
+    artist: str,
+    audio_url: str,
+    file_type: str,
+    album: str | None = None,
+    duration: int | None = None,
+) -> str:
+    """create app.relay.track record on user's PDS.
+
+    returns: record URI (at://did:plc:.../app.relay.track/tid)
+    """
+    # get OAuth session with DPoP tokens
+    oauth_session = await get_oauth_session(auth_session.session_id)
+
+    # create authenticated client
+    client = Client(pds_url=oauth_session.pds_url)
+    client.set_access_token(oauth_session.access_token)
+
+    # create record
+    record = {
+        "$type": "app.relay.track",
+        "title": title,
+        "artist": artist,
+        "audioUrl": audio_url,
+        "fileType": file_type,
+        "createdAt": datetime.utcnow().isoformat() + "Z",
+    }
+    if album:
+        record["album"] = album
+    if duration:
+        record["duration"] = duration
+
+    # write to PDS
+    response = client.com.atproto.repo.create_record({
+        "repo": auth_session.did,
+        "collection": "app.relay.track",
+        "record": record,
+    })
+
+    return response.uri
+```
+
+### phase 3: ATProto record indexing
+
+**goal**: discover tracks from other users via firehose or appview
+
+**tasks**:
+1. set up jetstream firehose consumer (similar to status project)
+2. listen for `app.relay.track` records
+3. index discovered tracks in local database
+4. add "discover" page showing tracks from network
+
+**deferred**: this is lower priority. focus on upload and playback first.
+
+## data flow diagrams
+
+### upload flow (phase 2)
+```
+user uploads track
+  ↓
+relay backend validates file
+  ↓
+upload audio to R2
+  ↓ (returns public URL)
+create ATProto record on user's PDS
+  ↓ (includes R2 URL)
+save Track model locally (with record URI)
+  ↓
+return success to user
+```
+
+### playback flow (existing + phase 1)
+```
+user clicks track
+  ↓
+frontend requests /audio/{file_id}
+  ↓
+backend proxies from R2 (or redirects)
+  ↓
+audio streams to browser
+```
+
+### discovery flow (phase 3, future)
+```
+relay firehose consumer
+  ↓
+listens for app.relay.track commits
+  ↓
+fetches record from PDS
+  ↓
+verifies R2 URL exists
+  ↓
+indexes track in local database
+  ↓
+track appears in discovery feed
+```
+
+## OAuth scope considerations
+
+**current scopes**: we only request basic authentication scopes via OAuth 2.1.
+
+**required for record creation**: the OAuth session gives us write access to the user's PDS under their identity. we can create records in their repo without additional scopes.
+
+**NOT using `transition:generic`**: this scope is too broad (gives blanket approval). we're using standard OAuth with appropriate permissions for record creation.
+
+## privacy and user control
+
+### transparency
+- users see exactly what record we're creating (show JSON before writing)
+- optional: require explicit "publish" confirmation
+
+### data sovereignty
+- track metadata lives in user's PDS (they control it)
+- users can delete records via their PDS management tools
+- relay indexes records but doesn't own them
+
+### opt-in participation
+- uploading a track requires authentication
+- users explicitly choose to publish
+
+## testing strategy
+
+### phase 1 (R2)
+1. upload test file to R2
+2. verify public URL works
+3. test streaming playback
+4. measure latency vs filesystem
+
+### phase 2 (ATProto records)
+1. create test record on development PDS
+2. verify record appears in repo
+3. fetch record via AT URI
+4. test error handling (network failures, auth issues)
+
+### phase 3 (indexing)
+1. run local jetstream consumer
+2. create test record from different account
+3. verify relay indexes it
+4. test discovery feed
+
+## open questions
+
+1. **R2 authentication**: should audio URLs be signed (temporary) or public?
+   - option A: public URLs (simpler, but anyone with URL can access)
+   - option B: signed URLs with expiration (more secure, but complex)
+   - **recommendation**: start with public, add signing later if needed
+
+2. **record deletion**: when user deletes track, should we:
+   - delete R2 file immediately?
+   - delete ATProto record?
+   - tombstone record but keep R2 file?
+   - **recommendation**: delete both R2 file and record
+
+3. **versioning**: if user updates track metadata, should we:
+   - update existing record?
+   - create new record with new rkey?
+   - **recommendation**: update existing record (keep rkey stable)
+
+4. **discovery**: should we:
+   - run our own appview/indexer?
+   - use bluesky's firehose?
+   - start without discovery and add later?
+   - **recommendation**: defer discovery to phase 3
+
+## migration checklist
+
+- [ ] set up R2 bucket and credentials
+- [ ] implement R2 storage adapter
+- [ ] migrate existing files to R2
+- [ ] update audio serving to use R2
+- [ ] test end-to-end upload and playback
+- [ ] implement ATProto record creation
+- [ ] add record URI to Track model
+- [ ] test record creation on personal PDS
+- [ ] update frontend to show "published to ATProto" status
+- [ ] document record format for other clients
+
+## references
+
+- atproto repository spec: https://atproto.com/specs/repository
+- atproto lexicon spec: https://atproto.com/specs/lexicon
+- atproto data model: https://atproto.com/specs/data-model
+- cloudflare R2 docs: https://developers.cloudflare.com/r2/
+- example unofficial lexicon: `sandbox/at-me/docs/lexicon.md`

docs/cloudflare-deployment.md

···
+# cloudflare deployment guide
+
+## prerequisites
+
+1. cloudflare account
+2. domain configured in cloudflare (optional but recommended)
+3. wrangler CLI installed: `npm install -g wrangler`
+
+## setup steps
+
+### 1. create r2 bucket
+
+```bash
+wrangler r2 bucket create relay-audio
+```
+
+this creates the bucket for audio storage.
+
+### 2. generate r2 access keys
+
+in cloudflare dashboard:
+1. go to r2 > manage r2 api tokens
+2. create api token with read & write permissions
+3. save access key id and secret access key
+
+### 3. set backend secrets
+
+```bash
+cd /path/to/relay
+
+# database connection
+wrangler secret put DATABASE_URL
+# paste your neon postgres connection string
+
+# r2 credentials
+wrangler secret put AWS_ACCESS_KEY_ID
+wrangler secret put AWS_SECRET_ACCESS_KEY
+
+# atproto oauth
+wrangler secret put ATPROTO_CLIENT_ID
+wrangler secret put ATPROTO_CLIENT_SECRET
+```
+
+### 4. configure environment variables
+
+update `wrangler.toml` with your values:
+- r2 bucket name (should be `relay-audio`)
+- pds url (currently `https://pds.zzstoatzz.io`)
+- r2 endpoint url: `https://<your-account-id>.r2.cloudflarestorage.com`
+- r2 public url: custom domain or `https://pub-<id>.r2.dev`
+
+### 5. deploy backend (python workers)
+
+```bash
+# from project root
+wrangler deploy
+```
+
+this deploys your fastapi backend to cloudflare workers.
+
+note: you'll get a url like `https://relay-api.<your-subdomain>.workers.dev`
+
+### 6. configure frontend api url
+
+update `frontend/wrangler.toml`:
+```toml
+[env.production.vars]
+API_URL = "https://relay-api.<your-subdomain>.workers.dev"
+```
+
+### 7. deploy frontend (pages)
+
+```bash
+cd frontend
+
+# build for production
+bun run build
+
+# deploy to pages
+wrangler pages deploy .svelte-kit/cloudflare --project-name relay-frontend
+```
+
+you'll get a url like `https://relay-frontend.pages.dev`
+
+### 8. configure custom domains (optional)
+
+in cloudflare dashboard:
+1. **frontend**: pages > relay-frontend > custom domains
+   - add `relay.example.com`
+2. **backend**: workers > relay-api > triggers > custom domains
+   - add `api.relay.example.com`
+3. **r2 public access**: r2 > relay-audio > settings > public access
+   - add custom domain `audio.relay.example.com`
+
+## cost estimate
+
+### free tier (perfect for mvp):
+- pages: unlimited static requests, 100k function requests/day
+- workers: 100k requests/day
+- r2: 10 gb storage, 1m class a ops, 10m class b ops
+- **total: $0/month**
+
+### paid tier (when you grow):
+- workers: $5/month (10m requests)
+- r2: ~$0.015/gb-month (100 gb audio = $1.50/month)
+- **total: ~$5-10/month for moderate usage**
+
+## local development
+
+keep using current setup:
+```bash
+# backend
+uv run uvicorn relay.main:app --reload --port 8001
+
+# frontend
+cd frontend && bun run dev
+```
+
+## testing deployment locally
+
+```bash
+# test backend with wrangler
+wrangler dev
+
+# test frontend
+cd frontend && wrangler pages dev .svelte-kit/cloudflare
+```
+
+## troubleshooting
+
+### python workers issues
+- ensure `compatibility_flags = ["python_workers"]` in wrangler.toml
+- python workers are in beta - some packages may not work
+- use `pywrangler` for complex dependency bundling
+
+### r2 access issues
+- verify bucket exists: `wrangler r2 bucket list`
+- check secrets are set: `wrangler secret list`
+- ensure r2 endpoint url includes account id
+
+### cors issues
+- configure cors in workers for frontend access
+- update frontend api url to match workers deployment
+
+## next steps
+
+1. set up ci/cd with github actions
+2. configure domain dns in cloudflare
+3. enable cloudflare analytics
+4. set up error tracking (sentry, etc.)

docs/phase1-r2-implementation.md

···
+# phase 1: R2 storage implementation
+
+## overview
+
+migrate audio file storage from local filesystem to cloudflare R2 while maintaining the same interface for the rest of the application.
+
+## setup
+
+### 1. create R2 bucket
+
+```bash
+# via cloudflare dashboard or wrangler CLI
+wrangler r2 bucket create relay-audio
+```
+
+### 2. create API token
+
+in cloudflare dashboard:
+1. go to R2 → overview
+2. click "manage R2 API tokens"
+3. create token with:
+   - permissions: read & write
+   - bucket: relay-audio
+
+save the credentials:
+- access key id
+- secret access key
+- account id
+
+### 3. configure environment
+
+add to `.env`:
+```bash
+# cloudflare R2 configuration
+R2_ACCOUNT_ID=your-account-id-here
+R2_ACCESS_KEY_ID=your-access-key-id-here
+R2_SECRET_ACCESS_KEY=your-secret-access-key-here
+R2_BUCKET_NAME=relay-audio
+R2_PUBLIC_DOMAIN=relay-audio.your-account.r2.cloudflarestorage.com
+```
+
+### 4. add dependencies
+
+```bash
+uv add boto3 boto3-stubs[s3]
+```
+
+## implementation
+
+### config.py updates
+
+add R2 configuration to existing config:
+
+```python
+# src/relay/config.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # ... existing settings ...
+
+    # r2 storage
+    r2_account_id: str | None = None
+    r2_access_key_id: str | None = None
+    r2_secret_access_key: str | None = None
+    r2_bucket_name: str = "relay-audio"
+    r2_public_domain: str | None = None
+
+    # storage backend selection
+    storage_backend: str = "filesystem"  # or "r2"
+
+settings = Settings()
+```
+
+### R2 storage adapter
+
+create `src/relay/storage/r2.py`:
+
+```python
+"""cloudflare R2 storage for audio files."""
+
+import hashlib
+from pathlib import Path
+from typing import BinaryIO
+
+import boto3
+from botocore.config import Config
+
+from relay.config import settings
+from relay.models import AudioFormat
+
+
+class R2Storage:
+    """store audio files on cloudflare R2."""
+
+    def __init__(self):
+        """initialize R2 client."""
+        if not all([
+            settings.r2_account_id,
+            settings.r2_access_key_id,
+            settings.r2_secret_access_key,
+        ]):
+            raise ValueError("R2 credentials not configured in environment")
+
+        # create boto3 s3 client for R2
+        self.client = boto3.client(
+            "s3",
+            endpoint_url=f"https://{settings.r2_account_id}.r2.cloudflarestorage.com",
+            aws_access_key_id=settings.r2_access_key_id,
+            aws_secret_access_key=settings.r2_secret_access_key,
+            config=Config(signature_version="s3v4"),
+        )
+        self.bucket_name = settings.r2_bucket_name
+        self.public_domain = settings.r2_public_domain
+
+    def save(self, file: BinaryIO, filename: str) -> str:
+        """save audio file to R2 and return file id."""
+        # read file content
+        content = file.read()
+
+        # generate file id from content hash
+        file_id = hashlib.sha256(content).hexdigest()[:16]
+
+        # determine file extension
+        ext = Path(filename).suffix.lower()
+        audio_format = AudioFormat.from_extension(ext)
+        if not audio_format:
+            raise ValueError(
+                f"unsupported file type: {ext}. "
+                f"supported: {AudioFormat.supported_extensions_str()}"
+            )
+
+        # construct s3 key
+        key = f"audio/{file_id}{ext}"
+
+        # upload to R2
+        self.client.put_object(
+            Bucket=self.bucket_name,
+            Key=key,
+            Body=content,
+            ContentType=audio_format.media_type,
+        )
+
+        return file_id
+
+    def get_url(self, file_id: str) -> str | None:
+        """get public URL for audio file."""
+        # try to find file with any supported extension
+        for audio_format in AudioFormat:
+            key = f"audio/{file_id}{audio_format.extension}"
+
+            # check if object exists
+            try:
+                self.client.head_object(Bucket=self.bucket_name, Key=key)
+                # object exists, return public URL
+                if self.public_domain:
+                    return f"https://{self.public_domain}/{key}"
+                return f"https://{settings.r2_account_id}.r2.cloudflarestorage.com/{self.bucket_name}/{key}"
+            except self.client.exceptions.ClientError:
+                continue
+
+        return None
+
+    def delete(self, file_id: str) -> bool:
+        """delete audio file from R2."""
+        for audio_format in AudioFormat:
+            key = f"audio/{file_id}{audio_format.extension}"
+
+            try:
+                self.client.delete_object(Bucket=self.bucket_name, Key=key)
+                return True
+            except self.client.exceptions.ClientError:
+                continue
+
+        return False
+```
+
+### update storage __init__.py
+
+modify `src/relay/storage/__init__.py` to support both backends:
+
+```python
+"""storage implementations."""
+
+from relay.config import settings
+
+if settings.storage_backend == "r2":
+    from relay.storage.r2 import R2Storage
+    storage = R2Storage()
+else:
+    from relay.storage.filesystem import FilesystemStorage
+    storage = FilesystemStorage()
+
+__all__ = ["storage"]
+```
+
+### update audio endpoint
+
+modify `src/relay/api/audio.py` to handle R2 URLs:
+
+```python
+"""audio streaming endpoints."""
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse, RedirectResponse
+
+from relay.config import settings
+from relay.models import AudioFormat
+from relay.storage import storage
+
+router = APIRouter(prefix="/audio", tags=["audio"])
+
+
[e-mail]("/{file_id}")
+async def stream_audio(file_id: str):
+    """stream audio file."""
+
+    if settings.storage_backend == "r2":
+        # R2: redirect to public URL
+        from relay.storage.r2 import R2Storage
+        if isinstance(storage, R2Storage):
+            url = storage.get_url(file_id)
+            if not url:
+                raise HTTPException(status_code=404, detail="audio file not found")
+            return RedirectResponse(url=url)
+
+    # filesystem: serve file directly
+    file_path = storage.get_path(file_id)
+
+    if not file_path:
+        raise HTTPException(status_code=404, detail="audio file not found")
+
+    # determine media type based on extension
+    audio_format = AudioFormat.from_extension(file_path.suffix)
+    media_type = audio_format.media_type if audio_format else "audio/mpeg"
+
+    return FileResponse(
+        path=file_path,
+        media_type=media_type,
+        filename=file_path.name,
+    )
+```
+
+## migration strategy
+
+### option A: immediate switch (recommended for MVP)
+
+1. set `STORAGE_BACKEND=r2` in `.env`
+2. restart backend
+3. all new uploads go to R2
+4. old files remain on filesystem (lazy migration)
+
+### option B: migrate existing files
+
+create migration script `scripts/migrate_to_r2.py`:
+
+```python
+"""migrate existing audio files from filesystem to R2."""
+
+import sys
+from pathlib import Path
+
+from relay.config import settings
+from relay.models import Track, get_db
+from relay.storage.filesystem import FilesystemStorage
+from relay.storage.r2 import R2Storage
+
+
+def migrate():
+    """migrate all audio files from filesystem to R2."""
+    fs_storage = FilesystemStorage()
+    r2_storage = R2Storage()
+
+    db = next(get_db())
+    tracks = db.query(Track).all()
+
+    print(f"migrating {len(tracks)} tracks...")
+
+    for track in tracks:
+        file_id = track.file_id
+        file_path = fs_storage.get_path(file_id)
+
+        if not file_path:
+            print(f"warning: file not found for track {track.id}: {file_id}")
+            continue
+
+        # upload to R2
+        with open(file_path, "rb") as f:
+            try:
+                r2_storage.save(f, file_path.name)
+                print(f"migrated: {track.title} ({file_id})")
+            except Exception as e:
+                print(f"error migrating {file_id}: {e}")
+                continue
+
+    print("migration complete!")
+
+
+if __name__ == "__main__":
+    migrate()
+```
+
+run migration:
+```bash
+uv run python scripts/migrate_to_r2.py
+```
+
+## testing
+
+### 1. upload test
+
+```bash
+# upload a track via portal
+curl -X POST http://localhost:8001/tracks/ \
+  -H "Cookie: session_id=your-session" \
+  -F "file=@test.mp3" \
+  -F "title=test track" \
+  -F "artist=test artist"
+```
+
+verify:
+- file appears in R2 bucket (via cloudflare dashboard)
+- track plays in frontend
+- URL in browser network tab points to R2
+
+### 2. streaming test
+
+```bash
+# get direct URL
+curl -I http://localhost:8001/audio/{file_id}
+
+# should see 307 redirect to R2 URL
+# or 200 with file content if using filesystem
+```
+
+### 3. deletion test
+
+```bash
+# delete via portal or API
+curl -X DELETE http://localhost:8001/tracks/{track_id} \
+  -H "Cookie: session_id=your-session"
+```
+
+verify:
+- file removed from R2 bucket
+- track removed from database
+
+## rollback plan
+
+if R2 has issues:
+
+1. set `STORAGE_BACKEND=filesystem` in `.env`
+2. restart backend
+3. files on filesystem still work
+4. new uploads go to filesystem
+
+## performance considerations
+
+### latency
+- R2 redirect adds ~100ms vs direct file serve
+- acceptable for MVP, optimize later if needed
+
+### bandwidth
+- R2 egress is free to cloudflare CDN
+- direct serve uses backend bandwidth
+
+### caching
+- add `Cache-Control` headers for R2 objects:
+```python
+self.client.put_object(
+    # ...
+    CacheControl="public, max-age=31536000",  # 1 year
+)
+```
+
+## security considerations
+
+### public URLs
+- R2 bucket needs public read access enabled
+- anyone with URL can access file
+- acceptable for MVP (music is meant to be shared)
+
+### signed URLs (future enhancement)
+if you need temporary access:
+```python
+def get_signed_url(self, file_id: str, expires_in: int = 3600) -> str:
+    """generate signed URL with expiration."""
+    key = f"audio/{file_id}.mp3"
+    return self.client.generate_presigned_url(
+        "get_object",
+        Params={"Bucket": self.bucket_name, "Key": key},
+        ExpiresIn=expires_in,
+    )
+```
+
+## cost estimates
+
+cloudflare R2 pricing (as of 2025):
+- storage: $0.015/GB/month
+- class A operations (writes): $4.50/million
+- class B operations (reads): $0.36/million
+- egress: free
+
+example costs for 1000 tracks:
+- storage: ~10GB = $0.15/month
+- uploads: 1000 tracks = $0.005
+- streams: 10k plays = $0.004
+- **total: ~$0.16/month**
+
+## next steps
+
+after R2 migration is working:
+
+1. add R2 URL to Track model for phase 2:
+```python
+class Track(Base):
+    # ... existing fields ...
+    atproto_record_uri: Mapped[str | None] = mapped_column(String, nullable=True)
+    r2_url: Mapped[str | None] = mapped_column(String, nullable=True)
+```
+
+2. proceed to phase 2: ATProto record creation

docs/phase2-atproto-records.md

···
+# phase 2: ATProto record creation
+
+## overview
+
+write track metadata to user's PDS when they upload audio. the record contains R2 URLs and metadata, creating a decentralized, user-owned music catalog.
+
+## prerequisites
+
+- phase 1 complete (R2 storage working)
+- OAuth 2.1 authentication working (already done)
+- user has valid session with access tokens
+
+## implementation
+
+### 1. update Track model
+
+add ATProto record tracking:
+
+```python
+# src/relay/models/track.py
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from relay.models.database import Base
+
+
+class Track(Base):
+    """track model."""
+
+    __tablename__ = "tracks"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    artist: Mapped[str] = mapped_column(String, nullable=False)
+    album: Mapped[str | None] = mapped_column(String, nullable=True)
+    duration: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    file_id: Mapped[str] = mapped_column(String, nullable=False, unique=True)
+    file_type: Mapped[str] = mapped_column(String, nullable=False)
+    artist_did: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    artist_handle: Mapped[str] = mapped_column(String, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        nullable=False,
+    )
+
+    # ATProto integration fields
+    r2_url: Mapped[str | None] = mapped_column(String, nullable=True)
+    atproto_record_uri: Mapped[str | None] = mapped_column(String, nullable=True)
+    atproto_record_cid: Mapped[str | None] = mapped_column(String, nullable=True)
+```
+
+### 2. create ATProto records module
+
+create `src/relay/atproto/records.py`:
+
+```python
+"""ATProto record creation for relay tracks."""
+
+from datetime import datetime, timezone
+
+from atproto import Client
+from atproto.exceptions import AtProtocolError
+
+from relay.auth import Session as AuthSession
+from relay.auth import oauth_client
+
+
+async def create_track_record(
+    auth_session: AuthSession,
+    title: str,
+    artist: str,
+    audio_url: str,
+    file_type: str,
+    album: str | None = None,
+    duration: int | None = None,
+) -> tuple[str, str]:
+    """create app.relay.track record on user's PDS.
+
+    args:
+        auth_session: authenticated user session
+        title: track title
+        artist: artist name
+        audio_url: R2 URL for audio file
+        file_type: file extension (mp3, wav, etc)
+        album: optional album name
+        duration: optional duration in seconds
+
+    returns:
+        tuple of (record_uri, record_cid)
+
+    raises:
+        AtProtocolError: if record creation fails
+        ValueError: if session is invalid
+    """
+    # get OAuth session with tokens
+    oauth_session = oauth_client.get_session(auth_session.session_id)
+    if not oauth_session:
+        raise ValueError("OAuth session not found")
+
+    # create authenticated client
+    # note: your atproto fork's Client needs PDS URL and access token
+    client = Client(base_url=oauth_session.pds_url)
+
+    # set access token from OAuth session
+    # this varies based on your fork's implementation
+    # check sandbox/atproto-fork for exact API
+    client.login(
+        access_jwt=oauth_session.access_token,
+        refresh_jwt=oauth_session.refresh_token if hasattr(oauth_session, 'refresh_token') else None,
+    )
+
+    # construct record
+    record = {
+        "$type": "app.relay.track",
+        "title": title,
+        "artist": artist,
+        "audioUrl": audio_url,
+        "fileType": file_type,
+        "createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    # add optional fields
+    if album:
+        record["album"] = album
+    if duration:
+        record["duration"] = duration
+
+    # write to PDS
+    response = await client.com.atproto.repo.create_record(
+        repo=auth_session.did,
+        collection="app.relay.track",
+        record=record,
+    )
+
+    return response.uri, response.cid
+```
+
+### 3. update upload endpoint
+
+modify `src/relay/api/tracks.py` to create ATProto records:
+
+```python
+"""tracks api endpoints."""
+
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from sqlalchemy.orm import Session
+
+from relay.atproto.records import create_track_record
+from relay.auth import Session as AuthSession
+from relay.auth import require_auth
+from relay.config import settings
+from relay.models import AudioFormat, Track, get_db
+from relay.storage import storage
+
+router = APIRouter(prefix="/tracks", tags=["tracks"])
+
+
[e-mail]("/")
+async def upload_track(
+    title: Annotated[str, Form()],
+    artist: Annotated[str, Form()],
+    album: Annotated[str | None, Form()] = None,
+    file: UploadFile = File(...),
+    auth_session: AuthSession = Depends(require_auth),
+    db: Session = Depends(get_db),
+) -> dict:
+    """upload a new track (requires authentication)."""
+    # validate file type
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="no filename provided")
+
+    ext = Path(file.filename).suffix.lower()
+    audio_format = AudioFormat.from_extension(ext)
+    if not audio_format:
+        raise HTTPException(
+            status_code=400,
+            detail=f"unsupported file type: {ext}. "
+            f"supported: {AudioFormat.supported_extensions_str()}",
+        )
+
+    # save audio file to R2
+    try:
+        file_id = storage.save(file.file, file.filename)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    # get R2 URL
+    if settings.storage_backend == "r2":
+        from relay.storage.r2 import R2Storage
+        if isinstance(storage, R2Storage):
+            r2_url = storage.get_url(file_id)
+        else:
+            r2_url = None
+    else:
+        # filesystem: construct relay backend URL
+        r2_url = f"http://localhost:8001/audio/{file_id}"
+
+    # create ATProto record (if R2 URL available)
+    atproto_uri = None
+    atproto_cid = None
+    if r2_url and settings.storage_backend == "r2":
+        try:
+            atproto_uri, atproto_cid = await create_track_record(
+                auth_session=auth_session,
+                title=title,
+                artist=artist,
+                audio_url=r2_url,
+                file_type=ext[1:],  # remove dot
+                album=album,
+                duration=None,  # TODO: extract from audio file
+            )
+        except Exception as e:
+            # log but don't fail upload if record creation fails
+            print(f"warning: failed to create ATProto record: {e}")
+
+    # create track record in local database
+    track = Track(
+        title=title,
+        artist=artist,
+        album=album,
+        file_id=file_id,
+        file_type=ext[1:],
+        artist_did=auth_session.did,
+        artist_handle=auth_session.handle,
+        r2_url=r2_url,
+        atproto_record_uri=atproto_uri,
+        atproto_record_cid=atproto_cid,
+    )
+
+    db.add(track)
+    db.commit()
+    db.refresh(track)
+
+    return {
+        "id": track.id,
+        "title": track.title,
+        "artist": track.artist,
+        "album": track.album,
+        "file_id": track.file_id,
+        "file_type": track.file_type,
+        "artist_did": track.artist_did,
+        "artist_handle": track.artist_handle,
+        "r2_url": track.r2_url,
+        "atproto_record_uri": track.atproto_record_uri,
+        "created_at": track.created_at.isoformat(),
+    }
+```
+
+## checking your atproto fork API
+
+since you're using a custom fork, check the actual client API:
+
+```bash
+# look at client implementation
+cat sandbox/atproto-fork/packages/atproto_client/atproto_client/client.py | grep -A 20 "class Client"
+
+# or check examples
+cat sandbox/atproto-fork/examples/*/main.py
+```
+
+key questions to answer:
+1. how to initialize authenticated client with OAuth tokens?
+2. does it use `client.login()` or set tokens directly?
+3. what's the method signature for `create_record()`?
+
+## database migration
+
+create migration for new columns:
+
+```bash
+# if using alembic
+alembic revision -m "add atproto fields to tracks"
+```
+
+or manual SQL:
+```sql
+ALTER TABLE tracks ADD COLUMN r2_url VARCHAR;
+ALTER TABLE tracks ADD COLUMN atproto_record_uri VARCHAR;
+ALTER TABLE tracks ADD COLUMN atproto_record_cid VARCHAR;
+```
+
+for MVP, just delete the database:
+```bash
+rm data/relay.db
+# restart backend (will recreate tables)
+```
+
+## testing
+
+### 1. upload with record creation
+
+```bash
+# upload via authenticated session
+curl -X POST http://localhost:8001/tracks/ \
+  -H "Cookie: session_id=your-session" \
+  -F "file=@test.mp3" \
+  -F "title=test track" \
+  -F "artist=test artist"
+
+# response should include:
+{
+  "atproto_record_uri": "at://did:plc:abc123/app.relay.track/3k2j4h5g6h",
+  "r2_url": "https://relay-audio.r2.cloudflarestorage.com/audio/abc123.mp3",
+  ...
+}
+```
+
+### 2. verify record on PDS
+
+use ATProto tools to check record exists:
+
+```python
+from atproto import Client
+
+client = Client()
+client.login("your-handle", "your-app-password")
+
+# get record
+record = client.com.atproto.repo.get_record(
+    repo="your-did",
+    collection="app.relay.track",
+    rkey="3k2j4h5g6h",
+)
+
+print(record)
+# should show: title, artist, audioUrl, etc.
+```
+
+### 3. check via at-me or similar tool
+
+visit your at-me visualization:
+- should see `app.relay.track` collection
+- records should list all uploaded tracks
+- each record should have R2 URL in `audioUrl` field
+
+## error handling
+
+### OAuth token expired
+
+```python
+try:
+    atproto_uri, atproto_cid = await create_track_record(...)
+except AtProtocolError as e:
+    if "token" in str(e).lower():
+        # token expired, refresh and retry
+        await oauth_client.refresh_session(auth_session.session_id)
+        atproto_uri, atproto_cid = await create_track_record(...)
+    else:
+        raise
+```
+
+### network failure
+
+```python
+import asyncio
+
+try:
+    atproto_uri, atproto_cid = await asyncio.wait_for(
+        create_track_record(...),
+        timeout=10.0,  # 10 second timeout
+    )
+except asyncio.TimeoutError:
+    print("atproto record creation timed out")
+    atproto_uri = None
+    atproto_cid = None
+```
+
+### PDS unavailable
+
+gracefully degrade:
+- save track locally without record
+- add background job to retry record creation later
+- show user "publishing to atproto..." status
+
+## frontend updates
+
+update portal page to show ATProto status:
+
+```svelte
+<!-- frontend/src/routes/portal/+page.svelte -->
+
+{#each tracks as track}
+  <div class="track-item">
+    <div class="track-info">
+      <div class="track-title">{track.title}</div>
+      <div class="track-meta">
+        {track.artist}
+        {#if track.atproto_record_uri}
+          <span class="atproto-badge" title={track.atproto_record_uri}>
+            ✓ published to atproto
+          </span>
+        {/if}
+      </div>
+    </div>
+  </div>
+{/each}
+
+<style>
+  .atproto-badge {
+    color: #5ce87b;
+    font-size: 0.85rem;
+    margin-left: 0.5rem;
+  }
+</style>
+```
+
+## next steps
+
+### track discovery (phase 3)
+
+once records are being created:
+
+1. set up jetstream consumer (like status project)
+2. listen for `app.relay.track` commits
+3. index tracks from other users
+4. add discovery feed to frontend
+
+### metadata extraction
+
+add duration extraction:
+
+```bash
+uv add mutagen
+```
+
+```python
+from mutagen import File as MutagenFile
+
+def extract_audio_metadata(file_path: Path) -> dict:
+    """extract metadata from audio file."""
+    audio = MutagenFile(file_path)
+    return {
+        "duration": int(audio.info.length) if audio.info else None,
+        # add more metadata as needed
+    }
+```
+
+### record updates
+
+allow users to update track metadata:
+
+```python
+async def update_track_record(
+    auth_session: AuthSession,
+    record_uri: str,
+    **updates,
+) -> str:
+    """update existing record."""
+    # parse record URI to get rkey
+    rkey = record_uri.split("/")[-1]
+
+    # get current record
+    record = await client.com.atproto.repo.get_record(
+        repo=auth_session.did,
+        collection="app.relay.track",
+        rkey=rkey,
+    )
+
+    # update fields
+    record.update(updates)
+
+    # write back
+    response = await client.com.atproto.repo.put_record(
+        repo=auth_session.did,
+        collection="app.relay.track",
+        rkey=rkey,
+        record=record,
+    )
+
+    return response.cid
+```
+
+## security considerations
+
+### validate R2 URLs
+
+ensure URLs only point to your R2 bucket:
+
+```python
+def validate_r2_url(url: str) -> bool:
+    """ensure URL is from our R2 bucket."""
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    allowed_domains = [
+        settings.r2_public_domain,
+        f"{settings.r2_account_id}.r2.cloudflarestorage.com",
+    ]
+    return parsed.hostname in allowed_domains
+```
+
+### rate limiting
+
+prevent spam record creation:
+
+```python
+from fastapi_limiter import FastAPILimiter
+from fastapi_limiter.depends import RateLimiter
+
[e-mail]("/", dependencies=[Depends(RateLimiter(times=10, seconds=3600))])
+async def upload_track(...):
+    """upload track (max 10/hour)."""
+    ...
+```
+
+## monitoring
+
+### track record creation success rate
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+try:
+    atproto_uri, atproto_cid = await create_track_record(...)
+    logger.info(f"created atproto record: {atproto_uri}")
+except Exception as e:
+    logger.error(f"failed to create atproto record: {e}", exc_info=True)
+```
+
+### dashboard metrics
+
+add to admin panel:
+- total tracks uploaded
+- tracks with ATProto records
+- record creation success rate
+- average record creation latency
+
+## references
+
+- atproto repo spec: https://atproto.com/specs/repository
+- atproto lexicon spec: https://atproto.com/specs/lexicon
+- your atproto fork: `sandbox/atproto-fork/`
+- example record creation: `sandbox/at-me/` and `sandbox/status/`

docs/theming.md

···
+# theming guide
+
+## color system
+
+all colors are centralized in `frontend/src/lib/theme.ts` for easy customization.
+
+### current color palette
+
+#### backgrounds
+- **primary**: `#0a0a0a` - main app background
+- **secondary**: `#141414` - card backgrounds
+- **tertiary**: `#1a1a1a` - hover states
+- **hover**: `#1f1f1f` - active hover
+
+#### borders
+- **subtle**: `#282828` - default borders
+- **default**: `#333333` - emphasized borders
+- **emphasis**: `#444444` - strong borders
+
+#### text
+- **primary**: `#e8e8e8` - main text, titles
+- **secondary**: `#b0b0b0` - subtitles, labels
+- **tertiary**: `#808080` - meta info
+- **muted**: `#666666` - disabled/very subtle
+
+#### accents
+- **primary**: `#6a9fff` - links, buttons, highlights
+- **hover**: `#8ab3ff` - accent hover state
+- **muted**: `#4a7ddd` - subtle accent
+
+## changing colors
+
+### option 1: edit theme.ts (recommended)
+
+update `frontend/src/lib/theme.ts`:
+
+```typescript
+export const theme = {
+  colors: {
+    accent: {
+      primary: '#your-color',  // change this
+      hover: '#your-hover',
+      muted: '#your-muted'
+    }
+  }
+};
+```
+
+### option 2: global find/replace
+
+for quick experiments, find/replace these key colors:
+
+- **accent blue**: `#6a9fff` → your color
+- **bright text**: `#e8e8e8` → your color
+- **mid text**: `#b0b0b0` → your color
+- **muted text**: `#808080` → your color
+
+### option 3: user-configurable themes (future)
+
+the centralized theme.ts makes it easy to:
+1. create multiple theme objects (light, dark, custom)
+2. store user preference in localStorage
+3. apply theme via context or global state
+4. hot-swap at runtime
+
+example future implementation:
+
+```typescript
+// themes.ts
+export const themes = {
+  dark: { colors: { ... } },
+  light: { colors: { ... } },
+  custom: { colors: { ... } }
+};
+
+// app context
+let selectedTheme = $state('dark');
+let currentTheme = $derived(themes[selectedTheme]);
+```
+
+## design principles
+
+### contrast ratios
+- **titles** (`#e8e8e8` on `#0a0a0a`): 15:1 ratio
+- **body text** (`#b0b0b0` on `#0a0a0a`): 11:1 ratio
+- **meta text** (`#808080` on `#0a0a0a`): 7:1 ratio
+
+all exceed wcag aa standards for accessibility.
+
+### visual hierarchy
+1. **primary** - track titles, headings (`#e8e8e8`)
+2. **secondary** - artist names, navigation (`#b0b0b0`)
+3. **tertiary** - metadata, handles (`#808080`)
+4. **muted** - timestamps, separators (`#666666`)
+
+### accent usage
+- **primary action** - login button, playing indicator
+- **hover states** - interactive feedback
+- **links** - atproto record links
+- **borders** - active/playing track highlight
+
+## component-specific colors
+
+### trackitem
+- title: `#e8e8e8` (bright, pops)
+- artist: `#b0b0b0` (readable)
+- album: `#909090` (subtle)
+- handle: `#808080` (meta)
+- record link: `#6a9fff` (accent)
+
+### header
+- brand: `#e8e8e8` → `#6a9fff` on hover
+- tagline: `#909090`
+- nav links: `#b0b0b0` → `#e8e8e8` on hover
+- buttons: `#6a9fff` border
+
+### player
+- track title: `#e8e8e8`
+- artist: `#b0b0b0`
+- controls: inherit from parent
+- progress bar: accent colors
+
+## testing colors
+
+```bash
+# start dev server
+cd frontend && bun run dev
+
+# navigate to http://localhost:5173
+# check:
+# - track titles are clearly readable
+# - hover states provide feedback
+# - playing state is obvious
+# - links stand out but don't overpower
+```
+
+## future enhancements
+
+1. **css custom properties**: migrate to css variables for runtime theming
+2. **theme switcher**: ui control for theme selection
+3. **user themes**: allow custom color uploads
+4. **accessibility**: add high contrast mode
+5. **presets**: curated theme collections

fly.toml

···
+app = 'relay-api'
+primary_region = 'iad'
+
+[build]
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = 'stop'
+  auto_start_machines = true
+  min_machines_running = 0
+  processes = ['app']
+
+  [http_service.concurrency]
+    type = 'requests'
+    hard_limit = 250
+    soft_limit = 200
+
+[[vm]]
+  memory = '1gb'
+  cpu_kind = 'shared'
+  cpus = 1
+
+[env]
+  PORT = '8000'
+  STORAGE_BACKEND = 'r2'
+  R2_BUCKET = 'relay'
+  R2_ENDPOINT_URL = 'https://8feb33b5fb57ce2bc093bc6f4141f40a.r2.cloudflarestorage.com'
+  R2_PUBLIC_BUCKET_URL = 'https://pub-841ec0f5a7854eaab01292d44aca4820.r2.dev'
+  ATPROTO_PDS_URL = 'https://pds.zzstoatzz.io'
+
+# secrets to set via: fly secrets set KEY=value
+# - DATABASE_URL
+# - AWS_ACCESS_KEY_ID
+# - AWS_SECRET_ACCESS_KEY
+# - ATPROTO_CLIENT_ID (will be https://relay-api.fly.dev/client-metadata.json after deployment)
+# - ATPROTO_REDIRECT_URI (will be https://relay-api.fly.dev/auth/callback after deployment)

frontend/package.json

···
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
 	},
 	"devDependencies": {
-		"@sveltejs/adapter-auto": "^6.1.0",
+		"@sveltejs/adapter-auto": "^7.0.0",
+		"@sveltejs/adapter-vercel": "^6.1.1",
 		"@sveltejs/kit": "^2.43.2",
 		"@sveltejs/vite-plugin-svelte": "^6.2.0",
 		"svelte": "^5.39.5",

frontend/src/lib/components/Header.svelte

···
+<script lang="ts">
+	import type { User } from '$lib/types';
+
+	interface Props {
+		user: User | null;
+		onLogout: () => Promise<void>;
+	}
+
+	let { user, onLogout }: Props = $props();
+
+	let isAuthenticated = $derived(user !== null);
+</script>
+
+<header>
+	<div class="header-content">
+		<a href="/" class="brand">
+			<h1>relay</h1>
+			<p>music on atproto</p>
+		</a>
+
+		<nav>
+			{#if isAuthenticated}
+				<a href="/portal" class="nav-link">portal</a>
+				<span class="user-info">@{user.handle}</span>
+				<button onclick={onLogout} class="btn-secondary">logout</button>
+			{:else}
+				<a href="/login" class="btn-primary">login</a>
+			{/if}
+		</nav>
+	</div>
+</header>
+
+<style>
+	header {
+		border-bottom: 1px solid #333;
+		margin-bottom: 2rem;
+	}
+
+	.header-content {
+		max-width: 800px;
+		margin: 0 auto;
+		padding: 1.5rem 1rem;
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+	}
+
+	.brand {
+		text-decoration: none;
+		color: inherit;
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+	}
+
+	.brand:hover h1 {
+		color: #6a9fff;
+	}
+
+	h1 {
+		font-size: 1.5rem;
+		margin: 0;
+		color: #e8e8e8;
+		transition: color 0.2s;
+	}
+
+	.brand p {
+		margin: 0;
+		font-size: 0.85rem;
+		color: #909090;
+	}
+
+	nav {
+		display: flex;
+		align-items: center;
+		gap: 1rem;
+	}
+
+	.nav-link {
+		color: #b0b0b0;
+		text-decoration: none;
+		font-size: 0.9rem;
+		transition: color 0.2s;
+	}
+
+	.nav-link:hover {
+		color: #e8e8e8;
+	}
+
+	.user-info {
+		color: #909090;
+		font-size: 0.9rem;
+	}
+
+	.btn-primary {
+		background: transparent;
+		border: 1px solid #6a9fff;
+		color: #6a9fff;
+		padding: 0.5rem 1rem;
+		border-radius: 4px;
+		font-size: 0.9rem;
+		text-decoration: none;
+		transition: all 0.2s;
+		cursor: pointer;
+	}
+
+	.btn-primary:hover {
+		background: #6a9fff;
+		color: #0a0a0a;
+	}
+
+	.btn-secondary {
+		background: transparent;
+		border: 1px solid #444;
+		color: #b0b0b0;
+		padding: 0.5rem 1rem;
+		border-radius: 4px;
+		font-size: 0.9rem;
+		cursor: pointer;
+		transition: all 0.2s;
+	}
+
+	.btn-secondary:hover {
+		border-color: #666;
+		color: #e8e8e8;
+	}
+</style>

frontend/src/lib/components/TrackItem.svelte

···
+<script lang="ts">
+	import type { Track } from '$lib/types';
+
+	interface Props {
+		track: Track;
+		isPlaying?: boolean;
+		onPlay: (track: Track) => void;
+	}
+
+	let { track, isPlaying = false, onPlay }: Props = $props();
+</script>
+
+<button
+	class="track"
+	class:playing={isPlaying}
+	onclick={() => onPlay(track)}
+>
+	<div class="track-info">
+		<div class="track-title">{track.title}</div>
+		<div class="track-artist">
+			{track.artist}
+			{#if track.album}
+				<span class="album">- {track.album}</span>
+			{/if}
+		</div>
+		<div class="track-meta">
+			<span>@{track.artist_handle}</span>
+			{#if track.atproto_record_uri}
+				{@const parts = track.atproto_record_uri.split('/')}
+				{@const did = parts[2]}
+				{@const collection = parts[3]}
+				{@const rkey = parts[4]}
+				<span class="separator">•</span>
+				<a
+					href={`https://pds.zzstoatzz.io/xrpc/com.atproto.repo.getRecord?repo=${did}&collection=${collection}&rkey=${rkey}`}
+					target="_blank"
+					rel="noopener"
+					class="atproto-link"
+					onclick={(e) => e.stopPropagation()}
+				>
+					view record
+				</a>
+			{/if}
+		</div>
+	</div>
+</button>
+
+<style>
+	.track {
+		background: #141414;
+		border: 1px solid #282828;
+		border-left: 3px solid transparent;
+		padding: 1rem;
+		cursor: pointer;
+		text-align: left;
+		transition: all 0.15s ease-in-out;
+		width: 100%;
+	}
+
+	.track:hover {
+		background: #1a1a1a;
+		border-left-color: #6a9fff;
+		border-color: #333;
+		transform: translateX(2px);
+	}
+
+	.track.playing {
+		background: #1a2330;
+		border-left-color: #6a9fff;
+		border-color: #2a3a4a;
+	}
+
+	.track-title {
+		font-weight: 600;
+		font-size: 1.1rem;
+		margin-bottom: 0.25rem;
+		color: #e8e8e8;
+	}
+
+	.track-artist {
+		color: #b0b0b0;
+		margin-bottom: 0.25rem;
+	}
+
+	.album {
+		color: #909090;
+	}
+
+	.track-meta {
+		font-size: 0.85rem;
+		color: #808080;
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+	}
+
+	.track-meta .separator {
+		color: #555;
+	}
+
+	.atproto-link {
+		color: #6a9fff;
+		text-decoration: none;
+		font-size: 0.8rem;
+		transition: all 0.2s;
+		border-bottom: 1px solid transparent;
+	}
+
+	.atproto-link:hover {
+		color: #8ab3ff;
+		border-bottom-color: #8ab3ff;
+	}
+</style>

frontend/src/lib/config.ts

···
+import { browser } from '$app/environment';
+
+export const API_URL = browser
+	? (window.location.hostname === 'localhost'
+		? 'http://localhost:8001'
+		: 'https://relay-api.fly.dev')
+	: 'https://relay-api.fly.dev';

frontend/src/lib/theme.ts

···
+export const theme = {
+	colors: {
+		// backgrounds
+		bg: {
+			primary: '#0a0a0a',
+			secondary: '#141414',
+			tertiary: '#1a1a1a',
+			hover: '#1f1f1f'
+		},
+		// borders
+		border: {
+			subtle: '#282828',
+			default: '#333333',
+			emphasis: '#444444'
+		},
+		// text
+		text: {
+			primary: '#e8e8e8',
+			secondary: '#b0b0b0',
+			tertiary: '#808080',
+			muted: '#666666'
+		},
+		// accents
+		accent: {
+			primary: '#6a9fff',
+			hover: '#8ab3ff',
+			muted: '#4a7ddd'
+		},
+		// semantic
+		success: '#4ade80',
+		warning: '#fbbf24',
+		error: '#ef4444'
+	},
+	spacing: {
+		xs: '0.25rem',
+		sm: '0.5rem',
+		md: '1rem',
+		lg: '1.5rem',
+		xl: '2rem'
+	},
+	radius: {
+		sm: '4px',
+		md: '6px',
+		lg: '8px'
+	}
+};
+
+export type Theme = typeof theme;

frontend/src/lib/types.ts

···
+export interface Track {
+	id: number;
+	title: string;
+	artist: string;
+	album?: string;
+	file_id: string;
+	file_type: string;
+	artist_handle: string;
+	r2_url?: string;
+	atproto_record_uri?: string;
+}
+
+export interface User {
+	did: string;
+	handle: string;
+}

frontend/src/routes/+page.svelte

···
 <script lang="ts">
 	import { onMount } from 'svelte';
+	import TrackItem from '$lib/components/TrackItem.svelte';
+	import Header from '$lib/components/Header.svelte';
+	import type { Track, User } from '$lib/types';
+	import { API_URL } from '$lib/config';
 
-	interface Track {
-		id: number;
-		title: string;
-		artist: string;
-		album?: string;
-		file_id: string;
-		file_type: string;
-		artist_handle: string;
-	}
+	let tracks = $state<Track[]>([]);
+	let currentTrack = $state<Track | null>(null);
+	let audioElement = $state<HTMLAudioElement | undefined>(undefined);
+	let user = $state<User | null>(null);
 
-	interface User {
-		did: string;
-		handle: string;
-	}
+	// player state - using Svelte's built-in bindings
+	let paused = $state(true);
+	let currentTime = $state(0);
+	let duration = $state(0);
+	let volume = $state(0.7);
 
-	let tracks: Track[] = [];
-	let currentTrack: Track | null = null;
-	let audioElement: HTMLAudioElement;
-	let user: User | null = null;
+	// derived values
+	let hasTracks = $derived(tracks.length > 0);
+	let isAuthenticated = $derived(user !== null);
+	let formattedCurrentTime = $derived(formatTime(currentTime));
+	let formattedDuration = $derived(formatTime(duration));
 
 	onMount(async () => {
 		// check authentication
 		try {
-			const authResponse = await fetch('http://localhost:8000/auth/me', {
+			const authResponse = await fetch('`${API_URL}`/auth/me', {
 				credentials: 'include'
 			});
 			if (authResponse.ok) {
···
 		}
 
 		// load tracks
-		const response = await fetch('http://localhost:8000/tracks/');
+		const response = await fetch('`${API_URL}`/tracks/');
 		const data = await response.json();
 		tracks = data.tracks;
 	});
 
+	// Use $effect to reactively handle track changes only
+	let previousTrackId: number | null = null;
+	$effect(() => {
+		if (!currentTrack || !audioElement) return;
+
+		// Only load new track if it actually changed
+		if (currentTrack.id !== previousTrackId) {
+			previousTrackId = currentTrack.id;
+			audioElement.src = `${API_URL}/audio/${currentTrack.file_id}`;
+			audioElement.load();
+
+			if (!paused) {
+				audioElement.play().catch(err => {
+					console.error('playback failed:', err);
+					paused = true;
+				});
+			}
+		}
+	});
+
 	function playTrack(track: Track) {
-		currentTrack = track;
-		if (audioElement) {
-			audioElement.src = `http://localhost:8000/audio/${track.file_id}`;
-			audioElement.play();
+		if (currentTrack?.id === track.id) {
+			// toggle play/pause on same track
+			paused = !paused;
+		} else {
+			// switch tracks
+			currentTrack = track;
+			paused = false;
 		}
 	}
 
+	function formatTime(seconds: number): string {
+		if (!seconds || isNaN(seconds)) return '0:00';
+		const mins = Math.floor(seconds / 60);
+		const secs = Math.floor(seconds % 60);
+		return `${mins}:${secs.toString().padStart(2, '0')}`;
+	}
+
 	async function logout() {
-		await fetch('http://localhost:8000/auth/logout', {
+		await fetch('`${API_URL}`/auth/logout', {
 			method: 'POST',
 			credentials: 'include'
 		});
···
 	}
 </script>
 
+<Header {user} onLogout={logout} />
+
 <main>
-	<header>
-		<div class="header-top">
-			<div>
-				<h1>relay</h1>
-				<p>decentralized music on ATProto</p>
-			</div>
-			<div class="auth-section">
-				{#if user}
-					<span class="user-info">@{user.handle}</span>
-					<button onclick={logout} class="logout-btn">logout</button>
-				{:else}
-					<a href="/login" class="login-link">login</a>
-				{/if}
-			</div>
-		</div>
-		{#if user}
-			<a href="/portal">artist portal →</a>
-		{/if}
-	</header>
 
 	<section class="tracks">
 		<h2>latest tracks</h2>
-		{#if tracks.length === 0}
+		{#if !hasTracks}
 			<p class="empty">no tracks yet</p>
 		{:else}
 			<div class="track-list">
 				{#each tracks as track}
-					<button
-						class="track"
-						class:playing={currentTrack?.id === track.id}
-						onclick={() => playTrack(track)}
-					>
-						<div class="track-info">
-							<div class="track-title">{track.title}</div>
-							<div class="track-artist">
-								{track.artist}
-								{#if track.album}
-									<span class="album">- {track.album}</span>
-								{/if}
-							</div>
-							<div class="track-meta">@{track.artist_handle}</div>
-						</div>
-					</button>
+					<TrackItem
+						{track}
+						isPlaying={currentTrack?.id === track.id}
+						onPlay={playTrack}
+					/>
 				{/each}
 			</div>
 		{/if}
···
 
 	{#if currentTrack}
 		<div class="player">
-			<div class="now-playing">
-				<strong>{currentTrack.title}</strong> by {currentTrack.artist}
+			<audio
+				bind:this={audioElement}
+				bind:paused
+				bind:currentTime
+				bind:duration
+				bind:volume
+				onended={() => {
+					currentTime = 0;
+					paused = true;
+				}}
+			></audio>
+
+			<div class="player-content">
+				<div class="player-info">
+					<div class="player-title">{currentTrack.title}</div>
+					<div class="player-artist">{currentTrack.artist}</div>
+				</div>
+
+				<div class="player-controls">
+					<button class="control-btn" onclick={() => paused = !paused} title={paused ? 'Play' : 'Pause'}>
+						{#if !paused}
+							<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+								<rect x="6" y="4" width="4" height="16" rx="1"></rect>
+								<rect x="14" y="4" width="4" height="16" rx="1"></rect>
+							</svg>
+						{:else}
+							<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor">
+								<path d="M8 5v14l11-7z"></path>
+							</svg>
+						{/if}
+					</button>
+
+					<div class="time-control">
+						<span class="time">{formattedCurrentTime}</span>
+						<input
+							type="range"
+							class="seek-bar"
+							min="0"
+							max={duration || 0}
+							bind:value={currentTime}
+						/>
+						<span class="time">{formattedDuration}</span>
+					</div>
+
+					<div class="volume-control">
+						<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+							<polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"></polygon>
+							<path d="M15.54 8.46a5 5 0 0 1 0 7.07"></path>
+						</svg>
+						<input
+							type="range"
+							class="volume-bar"
+							min="0"
+							max="1"
+							step="0.01"
+							bind:value={volume}
+						/>
+					</div>
+				</div>
 			</div>
-			<audio bind:this={audioElement} controls></audio>
 		</div>
 	{/if}
 </main>
···
 	:global(body) {
 		margin: 0;
 		padding: 0;
-		font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+		font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code', 'Consolas', monospace;
 		background: #0a0a0a;
-		color: #fff;
+		color: #e0e0e0;
+		-webkit-font-smoothing: antialiased;
 	}
 
 	main {
 		max-width: 800px;
 		margin: 0 auto;
-		padding: 2rem 1rem 120px;
+		padding: 0 1rem 120px;
 	}
 
-	header {
-		margin-bottom: 3rem;
+	.tracks h2 {
+		font-size: 1.5rem;
+		margin-bottom: 1.5rem;
+		color: #e8e8e8;
 	}
 
-	.header-top {
-		display: flex;
-		justify-content: space-between;
-		align-items: flex-start;
-		margin-bottom: 1rem;
+	.empty {
+		color: #808080;
+		padding: 2rem;
+		text-align: center;
 	}
 
-	h1 {
-		font-size: 2.5rem;
-		margin: 0 0 0.5rem;
+	.track-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
 	}
 
-	header p {
-		color: #888;
-		margin: 0 0 1rem;
+	.player {
+		position: fixed;
+		bottom: 0;
+		left: 0;
+		right: 0;
+		background: #1a1a1a;
+		border-top: 1px solid #2a2a2a;
+		padding: 1rem;
+		z-index: 100;
 	}
 
-	.auth-section {
+	.player-content {
+		max-width: 1200px;
+		margin: 0 auto;
 		display: flex;
 		align-items: center;
-		gap: 1rem;
+		gap: 2rem;
 	}
 
-	.user-info {
-		color: #aaa;
-		font-size: 0.9rem;
+	.player-info {
+		flex: 0 0 200px;
+		min-width: 0;
 	}
 
-	.logout-btn {
-		background: transparent;
-		border: 1px solid #444;
-		color: #aaa;
-		padding: 0.4rem 0.8rem;
-		border-radius: 4px;
-		cursor: pointer;
-		font-size: 0.9rem;
-		transition: all 0.2s;
+	.player-title {
+		font-weight: 600;
+		font-size: 0.95rem;
+		margin-bottom: 0.25rem;
+		color: #e8e8e8;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
 	}
 
-	.logout-btn:hover {
-		border-color: #666;
-		color: #fff;
+	.player-artist {
+		color: #b0b0b0;
+		font-size: 0.85rem;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
 	}
 
-	.login-link {
-		color: #3a7dff;
-		text-decoration: none;
-		font-size: 0.9rem;
-		padding: 0.4rem 0.8rem;
-		border: 1px solid #3a7dff;
-		border-radius: 4px;
-		transition: all 0.2s;
+	.player-controls {
+		flex: 1;
+		display: flex;
+		align-items: center;
+		gap: 1.5rem;
 	}
 
-	.login-link:hover {
-		background: #3a7dff;
-		color: white;
+	.control-btn {
+		background: transparent;
+		border: none;
+		color: #fff;
+		cursor: pointer;
+		padding: 0.5rem;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		transition: all 0.2s;
+		border-radius: 50%;
 	}
 
-	header > a {
+	.control-btn:hover {
+		background: rgba(58, 125, 255, 0.1);
 		color: #3a7dff;
-		text-decoration: none;
-		font-size: 0.9rem;
 	}
 
-	header > a:hover {
-		text-decoration: underline;
+	.time-control {
+		flex: 1;
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
 	}
 
-	.tracks h2 {
-		font-size: 1.5rem;
-		margin-bottom: 1.5rem;
+	.time {
+		font-size: 0.8rem;
+		color: #888;
+		font-variant-numeric: tabular-nums;
+		min-width: 40px;
 	}
 
-	.empty {
-		color: #666;
-		padding: 2rem;
-		text-align: center;
-	}
-
-	.track-list {
-		display: flex;
-		flex-direction: column;
-		gap: 0.5rem;
+	.seek-bar {
+		flex: 1;
+		height: 4px;
+		-webkit-appearance: none;
+		appearance: none;
+		background: #2a2a2a;
+		border-radius: 2px;
+		outline: none;
+		cursor: pointer;
 	}
 
-	.track {
-		background: #1a1a1a;
-		border: 1px solid #2a2a2a;
-		border-left: 3px solid transparent;
-		padding: 1rem;
+	.seek-bar::-webkit-slider-thumb {
+		-webkit-appearance: none;
+		appearance: none;
+		width: 12px;
+		height: 12px;
+		background: #3a7dff;
+		border-radius: 50%;
 		cursor: pointer;
-		text-align: left;
 		transition: all 0.2s;
-		width: 100%;
 	}
 
-	.track:hover {
-		background: #222;
-		border-left-color: #3a7dff;
+	.seek-bar::-webkit-slider-thumb:hover {
+		background: #5a8fff;
+		transform: scale(1.2);
 	}
 
-	.track.playing {
-		background: #1a2332;
-		border-left-color: #3a7dff;
+	.seek-bar::-moz-range-thumb {
+		width: 12px;
+		height: 12px;
+		background: #3a7dff;
+		border-radius: 50%;
+		border: none;
+		cursor: pointer;
+		transition: all 0.2s;
 	}
 
-	.track-title {
-		font-weight: 600;
-		font-size: 1.1rem;
-		margin-bottom: 0.25rem;
+	.seek-bar::-moz-range-thumb:hover {
+		background: #5a8fff;
+		transform: scale(1.2);
 	}
 
-	.track-artist {
-		color: #aaa;
-		margin-bottom: 0.25rem;
+	.volume-control {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		flex: 0 0 120px;
 	}
 
-	.album {
+	.volume-control svg {
+		flex-shrink: 0;
 		color: #888;
 	}
 
-	.track-meta {
-		font-size: 0.85rem;
-		color: #666;
+	.volume-bar {
+		flex: 1;
+		height: 4px;
+		-webkit-appearance: none;
+		appearance: none;
+		background: #2a2a2a;
+		border-radius: 2px;
+		outline: none;
+		cursor: pointer;
 	}
 
-	.player {
-		position: fixed;
-		bottom: 0;
-		left: 0;
-		right: 0;
-		background: #1a1a1a;
-		border-top: 1px solid #2a2a2a;
-		padding: 1rem;
-		display: flex;
-		align-items: center;
-		gap: 1rem;
+	.volume-bar::-webkit-slider-thumb {
+		-webkit-appearance: none;
+		appearance: none;
+		width: 10px;
+		height: 10px;
+		background: #888;
+		border-radius: 50%;
+		cursor: pointer;
+		transition: all 0.2s;
 	}
 
-	.now-playing {
-		flex: 1;
-		min-width: 0;
+	.volume-bar::-webkit-slider-thumb:hover {
+		background: #aaa;
+		transform: scale(1.2);
 	}
 
-	.now-playing strong {
-		color: #fff;
+	.volume-bar::-moz-range-thumb {
+		width: 10px;
+		height: 10px;
+		background: #888;
+		border-radius: 50%;
+		border: none;
+		cursor: pointer;
+		transition: all 0.2s;
 	}
 
-	audio {
-		flex: 1;
-		max-width: 400px;
+	.volume-bar::-moz-range-thumb:hover {
+		background: #aaa;
+		transform: scale(1.2);
 	}
 </style>

frontend/src/routes/login/+page.svelte

···
 <script lang="ts">
+	import { API_URL } from '$lib/config';
+
 	let handle = '';
 	let loading = false;
 
-	function startOAuth() {
+	function startOAuth(e: SubmitEvent) {
+		e.preventDefault();
 		if (!handle.trim()) return;
 		loading = true;
 		// redirect to backend OAuth start endpoint
-		window.location.href = `http://localhost:8000/auth/start?handle=${encodeURIComponent(handle)}`;
+		window.location.href = `${API_URL}/auth/start?handle=${encodeURIComponent(handle)}`;
 	}
 </script>
 
···
 		<h1>relay</h1>
 		<p>decentralized music streaming</p>
 
-		<form on:submit|preventDefault={startOAuth}>
+		<form onsubmit={startOAuth}>
 			<div class="input-group">
-				<label for="handle">bluesky handle</label>
+				<label for="handle">atproto handle</label>
 				<input
 					id="handle"
 					type="text"
···
 			</div>
 
 			<button type="submit" disabled={loading || !handle.trim()}>
-				{loading ? 'redirecting...' : 'login with bluesky'}
+				{loading ? 'redirecting...' : 'sign in with atproto'}
 			</button>
 		</form>
 	</div>
 </div>
 
 <style>
+	:global(body) {
+		margin: 0;
+		padding: 0;
+		font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+		background: #0a0a0a;
+		color: #fff;
+	}
+
 	.container {
 		min-height: 100vh;
 		display: flex;
 		align-items: center;
 		justify-content: center;
-		background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+		background: #0a0a0a;
 		padding: 1rem;
 	}
 
 	.login-card {
-		background: #0f3460;
-		border-radius: 12px;
+		background: #1a1a1a;
+		border: 1px solid #2a2a2a;
+		border-radius: 8px;
 		padding: 3rem;
 		max-width: 400px;
 		width: 100%;
-		box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
 	}
 
 	h1 {
 		font-size: 2.5rem;
 		margin: 0 0 0.5rem 0;
-		color: #e94560;
+		color: #fff;
 		text-align: center;
 	}
 
 	p {
-		color: rgba(255, 255, 255, 0.7);
+		color: #888;
 		text-align: center;
 		margin: 0 0 2rem 0;
+		font-size: 0.95rem;
 	}
 
 	.input-group {
···
 
 	label {
 		display: block;
-		color: rgba(255, 255, 255, 0.9);
+		color: #aaa;
 		margin-bottom: 0.5rem;
 		font-size: 0.9rem;
 	}
···
 	input {
 		width: 100%;
 		padding: 0.75rem;
-		background: rgba(255, 255, 255, 0.05);
-		border: 1px solid rgba(255, 255, 255, 0.1);
-		border-radius: 6px;
+		background: #0a0a0a;
+		border: 1px solid #333;
+		border-radius: 4px;
 		color: white;
 		font-size: 1rem;
 		transition: all 0.2s;
+		box-sizing: border-box;
 	}
 
 	input:focus {
 		outline: none;
-		border-color: #e94560;
-		background: rgba(255, 255, 255, 0.08);
+		border-color: #3a7dff;
 	}
 
 	input:disabled {
···
 	}
 
 	input::placeholder {
-		color: rgba(255, 255, 255, 0.3);
+		color: #666;
 	}
 
 	button {
 		width: 100%;
 		padding: 0.75rem;
-		background: #e94560;
+		background: #3a7dff;
 		color: white;
 		border: none;
-		border-radius: 6px;
+		border-radius: 4px;
 		font-size: 1rem;
 		font-weight: 600;
 		cursor: pointer;
···
 	}
 
 	button:hover:not(:disabled) {
-		background: #d63651;
+		background: #2868e6;
 		transform: translateY(-1px);
-		box-shadow: 0 4px 12px rgba(233, 69, 96, 0.3);
+		box-shadow: 0 4px 12px rgba(58, 125, 255, 0.3);
 	}
 
 	button:disabled {

frontend/src/routes/portal/+page.svelte

···
 <script lang="ts">
 	import { onMount } from 'svelte';
-
-	interface User {
-		did: string;
-		handle: string;
-	}
+	import Header from '$lib/components/Header.svelte';
+	import type { User, Track} from '$lib/types';
+	import { API_URL } from '$lib/config';
 
 	let user: User | null = null;
 	let loading = true;
+	let tracks: Track[] = [];
+	let loadingTracks = false;
 
 	// form state
 	let uploading = false;
···
 
 	onMount(async () => {
 		try {
-			const response = await fetch('http://localhost:8000/auth/me', {
+			const response = await fetch('`${API_URL}`/auth/me', {
 				credentials: 'include'
 			});
 			if (response.ok) {
 				user = await response.json();
+				await loadMyTracks();
 			} else {
 				// not authenticated, redirect to login
 				window.location.href = '/login';
···
 		}
 	});
 
-	async function handleUpload(e: Event) {
+	async function loadMyTracks() {
+		loadingTracks = true;
+		try {
+			const response = await fetch('`${API_URL}`/tracks/me', {
+				credentials: 'include'
+			});
+			if (response.ok) {
+				const data = await response.json();
+				tracks = data.tracks;
+			}
+		} catch (e) {
+			console.error('failed to load tracks:', e);
+		} finally {
+			loadingTracks = false;
+		}
+	}
+
+	async function handleUpload(e: SubmitEvent) {
 		e.preventDefault();
 		if (!file) return;
 
···
 		if (album) formData.append('album', album);
 
 		try {
-			const response = await fetch('http://localhost:8000/tracks/', {
+			const response = await fetch('`${API_URL}`/tracks/', {
 				method: 'POST',
 				body: formData,
 				credentials: 'include'
···
 				file = null;
 				// @ts-ignore
 				document.getElementById('file-input').value = '';
+				// reload tracks
+				await loadMyTracks();
 			} else {
 				const error = await response.json();
 				uploadError = error.detail || `upload failed (${response.status} ${response.statusText})`;
···
 		}
 	}
 
+	async function deleteTrack(trackId: number, trackTitle: string) {
+		if (!confirm(`delete "${trackTitle}"?`)) return;
+
+		try {
+			const response = await fetch(`${API_URL}/tracks/${trackId}`, {
+				method: 'DELETE',
+				credentials: 'include'
+			});
+
+			if (response.ok) {
+				await loadMyTracks();
+			} else {
+				const error = await response.json();
+				alert(error.detail || 'failed to delete track');
+			}
+		} catch (e) {
+			alert(`network error: ${e instanceof Error ? e.message : 'unknown error'}`);
+		}
+	}
+
 	function handleFileChange(e: Event) {
 		const target = e.target as HTMLInputElement;
 		if (target.files && target.files[0]) {
 			file = target.files[0];
 		}
 	}
+
+	async function logout() {
+		await fetch('`${API_URL}`/auth/logout', {
+			method: 'POST',
+			credentials: 'include'
+		});
+		window.location.href = '/';
+	}
 </script>
 
 {#if loading}
 	<div class="loading">loading...</div>
 {:else if user}
+	<Header {user} onLogout={logout} />
 	<main>
-		<header>
-			<div class="header-content">
-				<div>
-					<h1>artist portal</h1>
-					<p class="user-info">logged in as @{user.handle}</p>
-				</div>
-				<a href="/" class="back-link">← back to tracks</a>
-			</div>
-		</header>
+		<div class="portal-header">
+			<h2>artist portal</h2>
+		</div>
 
 		<section class="upload-section">
 			<h2>upload track</h2>
···
 				<div class="message error">{uploadError}</div>
 			{/if}
 
-			<form on:submit={handleUpload}>
+			<form onsubmit={handleUpload}>
 				<div class="form-group">
 					<label for="title">track title</label>
 					<input
···
 						id="file-input"
 						type="file"
 						accept="audio/*"
-						on:change={handleFileChange}
+						onchange={handleFileChange}
 						required
 						disabled={uploading}
 					/>
···
 				</button>
 			</form>
 		</section>
+
+		<section class="tracks-section">
+			<h2>your tracks</h2>
+
+			{#if loadingTracks}
+				<p class="empty">loading tracks...</p>
+			{:else if tracks.length === 0}
+				<p class="empty">no tracks uploaded yet</p>
+			{:else}
+				<div class="tracks-list">
+					{#each tracks as track}
+						<div class="track-item">
+							<div class="track-info">
+								<div class="track-title">{track.title}</div>
+								<div class="track-meta">
+									{track.artist}
+									{#if track.album}
+										<span class="separator">•</span>
+										<span class="album">{track.album}</span>
+									{/if}
+								</div>
+								<div class="track-date">
+									{new Date(track.created_at).toLocaleDateString()}
+								</div>
+							</div>
+							<button
+								class="delete-btn"
+								onclick={() => deleteTrack(track.id, track.title)}
+								title="delete track"
+							>
+								×
+							</button>
+						</div>
+					{/each}
+				</div>
+			{/if}
+		</section>
 	</main>
 {/if}
 
 <style>
-	:global(body) {
-		margin: 0;
-		padding: 0;
-		font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-		background: #0a0a0a;
-		color: #fff;
-	}
-
 	.loading {
 		display: flex;
 		align-items: center;
···
 	main {
 		max-width: 800px;
 		margin: 0 auto;
-		padding: 2rem 1rem;
+		padding: 0 1rem 2rem;
 	}
 
-	header {
-		margin-bottom: 3rem;
-	}
-
-	.header-content {
-		display: flex;
-		justify-content: space-between;
-		align-items: flex-start;
-	}
-
-	h1 {
-		font-size: 2.5rem;
-		margin: 0 0 0.5rem;
+	.portal-header {
+		margin-bottom: 2rem;
 	}
 
-	.user-info {
-		color: #888;
+	.portal-header h2 {
+		font-size: 1.5rem;
 		margin: 0;
 	}
 
-	.back-link {
-		color: #3a7dff;
-		text-decoration: none;
-		font-size: 0.9rem;
-		padding: 0.5rem 1rem;
-		border: 1px solid #3a7dff;
-		border-radius: 4px;
-		transition: all 0.2s;
-	}
-
-	.back-link:hover {
-		background: #3a7dff;
-		color: white;
-	}
 
 	.upload-section h2 {
 		font-size: 1.5rem;
···
 
 	button:active:not(:disabled) {
 		transform: translateY(0);
+	}
+
+	.tracks-section {
+		margin-top: 3rem;
+	}
+
+	.tracks-section h2 {
+		font-size: 1.5rem;
+		margin-bottom: 1.5rem;
+	}
+
+	.empty {
+		color: #666;
+		padding: 2rem;
+		text-align: center;
+		background: #1a1a1a;
+		border-radius: 8px;
+		border: 1px solid #2a2a2a;
+	}
+
+	.tracks-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.75rem;
+	}
+
+	.track-item {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		background: #1a1a1a;
+		border: 1px solid #2a2a2a;
+		border-radius: 6px;
+		padding: 1rem;
+		transition: all 0.2s;
+	}
+
+	.track-item:hover {
+		background: #222;
+		border-color: #333;
+	}
+
+	.track-info {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.track-title {
+		font-weight: 600;
+		font-size: 1rem;
+		margin-bottom: 0.25rem;
+		color: #fff;
+	}
+
+	.track-meta {
+		font-size: 0.9rem;
+		color: #aaa;
+		margin-bottom: 0.25rem;
+	}
+
+	.separator {
+		margin: 0 0.5rem;
+		color: #666;
+	}
+
+	.album {
+		color: #888;
+	}
+
+	.track-date {
+		font-size: 0.85rem;
+		color: #666;
+	}
+
+	.delete-btn {
+		flex-shrink: 0;
+		width: 36px;
+		height: 36px;
+		padding: 0;
+		background: transparent;
+		border: 1px solid #444;
+		border-radius: 4px;
+		color: #888;
+		font-size: 1.5rem;
+		line-height: 1;
+		cursor: pointer;
+		transition: all 0.2s;
+		margin-left: 1rem;
+	}
+
+	.delete-btn:hover {
+		background: rgba(233, 69, 96, 0.1);
+		border-color: rgba(233, 69, 96, 0.5);
+		color: #ff6b6b;
+		transform: none;
+		box-shadow: none;
 	}
 </style>

frontend/svelte.config.js

···
-import adapter from '@sveltejs/adapter-auto';
+import adapter from '@sveltejs/adapter-vercel';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 
 /** @type {import('@sveltejs/kit').Config} */
 const config = {
-	// Consult https://svelte.dev/docs/kit/integrations
-	// for more information about preprocessors
 	preprocess: vitePreprocess(),
 
 	kit: {
-		// adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
-		// If your environment is not supported, or you settled on a specific environment, switch out the adapter.
-		// See https://svelte.dev/docs/kit/adapters for more information about adapters.
 		adapter: adapter()
 	}
 };

justfile

···
 
 # run backend server
 serve:
-    uv run uvicorn relay.main:app --reload --host 0.0.0.0 --port 8000
+    uv run uvicorn relay.main:app --reload --host 0.0.0.0 --port ${PORT:-8001}
 
 # run frontend dev server
 dev:

pyproject.toml

···
     "python-multipart>=0.0.20",
     "python-jose[cryptography]>=3.3.0",
     "passlib[bcrypt]>=1.7.4",
+    "psycopg[binary]>=3.2.12",
 ]
 
 requires-python = ">=3.11"

src/relay/api/audio.py

···
 """audio streaming endpoints."""
 
 from fastapi import APIRouter, HTTPException
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, RedirectResponse
 
+from relay.config import settings
 from relay.models import AudioFormat
 from relay.storage import storage
 
···
 
 
 @router.get("/{file_id}")
-async def stream_audio(file_id: str) -> FileResponse:
+async def stream_audio(file_id: str):
     """stream audio file."""
+
+    if settings.storage_backend == "r2":
+        # R2: redirect to public URL
+        from relay.storage.r2 import R2Storage
+        if isinstance(storage, R2Storage):
+            url = storage.get_url(file_id)
+            if not url:
+                raise HTTPException(status_code=404, detail="audio file not found")
+            return RedirectResponse(url=url)
+
+    # filesystem: serve file directly
     file_path = storage.get_path(file_id)
-    
+
     if not file_path:
         raise HTTPException(status_code=404, detail="audio file not found")
-    
+
     # determine media type based on extension
     audio_format = AudioFormat.from_extension(file_path.suffix)
     media_type = audio_format.media_type if audio_format else "audio/mpeg"
-    
+
     return FileResponse(
         path=file_path,
         media_type=media_type,

src/relay/api/auth.py

···
 
     # redirect to localhost endpoint to set cookie properly for localhost domain
     response = RedirectResponse(
-        url=f"http://localhost:8000/auth/session?session_id={session_id}",
+        url=f"http://localhost:8001/auth/session?session_id={session_id}",
         status_code=303
     )
     return response

src/relay/api/tracks.py

···
 from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
 from sqlalchemy.orm import Session
 
+from relay.atproto import create_track_record
 from relay.auth import Session as AuthSession
 from relay.auth import require_auth
+from relay.config import settings
 from relay.models import AudioFormat, Track, get_db
 from relay.storage import storage
 
···
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e)) from e
 
+    # get R2 URL
+    r2_url = None
+    if settings.storage_backend == "r2":
+        from relay.storage.r2 import R2Storage
+        if isinstance(storage, R2Storage):
+            r2_url = storage.get_url(file_id)
+
+    # create ATProto record (if R2 URL available)
+    atproto_uri = None
+    atproto_cid = None
+    if r2_url:
+        try:
+            atproto_uri, atproto_cid = await create_track_record(
+                auth_session=auth_session,
+                title=title,
+                artist=artist,
+                audio_url=r2_url,
+                file_type=ext[1:],  # remove dot
+                album=album,
+                duration=None,  # TODO: extract from audio file
+            )
+        except Exception as e:
+            # log but don't fail upload if record creation fails
+            print(f"warning: failed to create ATProto record: {e}")
+
     # create track record with artist identity
+    extra = {}
+    if album:
+        extra["album"] = album
+
     track = Track(
         title=title,
         artist=artist,
-        album=album,
         file_id=file_id,
         file_type=ext[1:],  # remove the dot
         artist_did=auth_session.did,
         artist_handle=auth_session.handle,
+        extra=extra,
+        r2_url=r2_url,
+        atproto_record_uri=atproto_uri,
+        atproto_record_cid=atproto_cid,
     )
 
     db.add(track)
···
         "file_type": track.file_type,
         "artist_did": track.artist_did,
         "artist_handle": track.artist_handle,
+        "r2_url": track.r2_url,
+        "atproto_record_uri": track.atproto_record_uri,
         "created_at": track.created_at.isoformat(),
     }
 
···
 async def list_tracks(db: Session = Depends(get_db)) -> dict:
     """list all tracks."""
     tracks = db.query(Track).order_by(Track.created_at.desc()).all()
-    
+
+    return {
+        "tracks": [
+            {
+                "id": track.id,
+                "title": track.title,
+                "artist": track.artist,
+                "album": track.album,
+                "file_id": track.file_id,
+                "file_type": track.file_type,
+                "artist_handle": track.artist_handle,
+                "r2_url": track.r2_url,
+                "atproto_record_uri": track.atproto_record_uri,
+                "created_at": track.created_at.isoformat(),
+            }
+            for track in tracks
+        ]
+    }
+
+
[e-mail]("/me")
+async def list_my_tracks(
+    auth_session: AuthSession = Depends(require_auth),
+    db: Session = Depends(get_db),
+) -> dict:
+    """list tracks uploaded by authenticated user."""
+    tracks = (
+        db.query(Track)
+        .filter(Track.artist_did == auth_session.did)
+        .order_by(Track.created_at.desc())
+        .all()
+    )
+
     return {
         "tracks": [
             {
···
                 "album": track.album,
                 "file_id": track.file_id,
                 "file_type": track.file_type,
+                "artist_handle": track.artist_handle,
+                "r2_url": track.r2_url,
+                "atproto_record_uri": track.atproto_record_uri,
                 "created_at": track.created_at.isoformat(),
             }
             for track in tracks
···
     }
 
 
[e-mail]("/{track_id}")
+async def delete_track(
+    track_id: int,
+    auth_session: AuthSession = Depends(require_auth),
+    db: Session = Depends(get_db),
+) -> dict:
+    """delete a track (only by owner)."""
+    track = db.query(Track).filter(Track.id == track_id).first()
+
+    if not track:
+        raise HTTPException(status_code=404, detail="track not found")
+
+    # verify ownership
+    if track.artist_did != auth_session.did:
+        raise HTTPException(
+            status_code=403,
+            detail="you can only delete your own tracks",
+        )
+
+    # delete audio file from storage
+    try:
+        storage.delete(track.file_id)
+    except Exception as e:
+        # log but don't fail - maybe file was already deleted
+        print(f"warning: failed to delete file {track.file_id}: {e}")
+
+    # delete track record
+    db.delete(track)
+    db.commit()
+
+    return {"message": "track deleted successfully"}
+
+
 @router.get("/{track_id}")
 async def get_track(track_id: int, db: Session = Depends(get_db)) -> dict:
     """get a specific track."""
     track = db.query(Track).filter(Track.id == track_id).first()
-    
+
     if not track:
         raise HTTPException(status_code=404, detail="track not found")
-    
+
     return {
         "id": track.id,
         "title": track.title,
···
         "album": track.album,
         "file_id": track.file_id,
         "file_type": track.file_type,
+        "artist_handle": track.artist_handle,
+        "r2_url": track.r2_url,
+        "atproto_record_uri": track.atproto_record_uri,
         "created_at": track.created_at.isoformat(),
     }

src/relay/atproto/__init__.py

···
+"""ATProto integration for relay."""
+
+from relay.atproto.records import create_track_record
+
+__all__ = ["create_track_record"]

src/relay/atproto/records.py

···
+"""ATProto record creation for relay tracks."""
+
+import json
+from datetime import datetime, timezone
+
+from atproto_oauth.models import OAuthSession
+
+from relay.auth import Session as AuthSession
+from relay.auth import oauth_client
+
+
+async def create_track_record(
+    auth_session: AuthSession,
+    title: str,
+    artist: str,
+    audio_url: str,
+    file_type: str,
+    album: str | None = None,
+    duration: int | None = None,
+) -> tuple[str, str]:
+    """create app.relay.track record on user's PDS.
+
+    args:
+        auth_session: authenticated user session
+        title: track title
+        artist: artist name
+        audio_url: R2 URL for audio file
+        file_type: file extension (mp3, wav, etc)
+        album: optional album name
+        duration: optional duration in seconds
+
+    returns:
+        tuple of (record_uri, record_cid)
+
+    raises:
+        ValueError: if session is invalid
+        Exception: if record creation fails
+    """
+    # get OAuth session data from database
+    oauth_data = auth_session.oauth_session
+    if not oauth_data or "access_token" not in oauth_data:
+        raise ValueError(f"OAuth session data missing or invalid for {auth_session.did}")
+
+    # reconstruct OAuthSession from database
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives import serialization
+
+    # deserialize DPoP private key
+    dpop_key_pem = oauth_data.get("dpop_private_key_pem")
+    if not dpop_key_pem:
+        raise ValueError("DPoP private key not found in session - please log out and log back in")
+
+    dpop_private_key = serialization.load_pem_private_key(
+        dpop_key_pem.encode("utf-8"),
+        password=None,
+        backend=default_backend(),
+    )
+
+    oauth_session = OAuthSession(
+        did=oauth_data["did"],
+        handle=oauth_data["handle"],
+        pds_url=oauth_data["pds_url"],
+        authserver_iss=oauth_data["authserver_iss"],
+        access_token=oauth_data["access_token"],
+        refresh_token=oauth_data["refresh_token"],
+        dpop_private_key=dpop_private_key,
+        dpop_authserver_nonce=oauth_data.get("dpop_authserver_nonce", ""),
+        dpop_pds_nonce=oauth_data.get("dpop_pds_nonce", ""),
+        scope=oauth_data["scope"],
+    )
+
+    # construct record
+    record = {
+        "$type": "app.relay.track",
+        "title": title,
+        "artist": artist,
+        "audioUrl": audio_url,
+        "fileType": file_type,
+        "createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    # add optional fields
+    if album:
+        record["album"] = album
+    if duration:
+        record["duration"] = duration
+
+    # make authenticated request to create record
+    url = f"{oauth_data['pds_url']}/xrpc/com.atproto.repo.createRecord"
+    payload = {
+        "repo": auth_session.did,
+        "collection": "app.relay.track",
+        "record": record,
+    }
+
+    response = await oauth_client.make_authenticated_request(
+        session=oauth_session,
+        method="POST",
+        url=url,
+        json=payload,
+    )
+
+    if response.status_code not in (200, 201):
+        raise Exception(
+            f"Failed to create ATProto record: {response.status_code} {response.text}"
+        )
+
+    result = response.json()
+    return result["uri"], result["cid"]

src/relay/auth.py

···
 """OAuth 2.1 authentication and session management."""
 
+import json
 import secrets
 from dataclasses import dataclass
 from typing import Annotated
···
 from fastapi import Cookie, HTTPException
 
 from relay.config import settings
+from relay.models import UserSession, get_db
 
 
 @dataclass
···
     handle: str
     oauth_session: dict  # store OAuth session data
 
+    def get_oauth_session_id(self) -> str:
+        """extract OAuth session ID for retrieving from session store."""
+        return self.oauth_session.get("session_id", self.did)
 
-# in-memory stores (MVP - replace with redis/db later)
-_sessions: dict[str, Session] = {}
+
+# OAuth stores (state store still in-memory for now)
 _state_store = MemoryStateStore()
 _session_store = MemorySessionStore()
 
···
 oauth_client = OAuthClient(
     client_id=settings.atproto_client_id,
     redirect_uri=settings.atproto_redirect_uri,
-    scope="atproto",
+    scope="atproto repo:app.relay.track",
     state_store=_state_store,
     session_store=_session_store,
 )
···
 def create_session(did: str, handle: str, oauth_session: dict) -> str:
     """create a new session for authenticated user."""
     session_id = secrets.token_urlsafe(32)
-    _sessions[session_id] = Session(
-        session_id=session_id,
-        did=did,
-        handle=handle,
-        oauth_session=oauth_session,
-    )
+
+    # store in database
+    db = next(get_db())
+    try:
+        db_session = UserSession(
+            session_id=session_id,
+            did=did,
+            handle=handle,
+            oauth_session_data=json.dumps(oauth_session),
+        )
+        db.add(db_session)
+        db.commit()
+    finally:
+        db.close()
+
     return session_id
 
 
 def get_session(session_id: str) -> Session | None:
     """retrieve session by id."""
-    return _sessions.get(session_id)
+    db = next(get_db())
+    try:
+        db_session = db.query(UserSession).filter(
+            UserSession.session_id == session_id
+        ).first()
+
+        if not db_session:
+            return None
+
+        return Session(
+            session_id=db_session.session_id,
+            did=db_session.did,
+            handle=db_session.handle,
+            oauth_session=json.loads(db_session.oauth_session_data),
+        )
+    finally:
+        db.close()
 
 
 def delete_session(session_id: str) -> None:
     """delete a session."""
-    _sessions.pop(session_id, None)
+    db = next(get_db())
+    try:
+        db.query(UserSession).filter(
+            UserSession.session_id == session_id
+        ).delete()
+        db.commit()
+    finally:
+        db.close()
 
 
 async def start_oauth_flow(handle: str) -> tuple[str, str]:
···
             state=state,
             iss=iss,
         )
-        # OAuth session is already stored in session_store, just extract key info
+
+        # serialize DPoP private key for storage
+        from cryptography.hazmat.primitives import serialization
+
+        dpop_key_pem = oauth_session.dpop_private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        ).decode("utf-8")
+
+        # store full OAuth session with tokens in database
         session_data = {
             "did": oauth_session.did,
             "handle": oauth_session.handle,
             "pds_url": oauth_session.pds_url,
             "authserver_iss": oauth_session.authserver_iss,
             "scope": oauth_session.scope,
+            "access_token": oauth_session.access_token,
+            "refresh_token": oauth_session.refresh_token,
+            "dpop_private_key_pem": dpop_key_pem,
+            "dpop_authserver_nonce": oauth_session.dpop_authserver_nonce,
+            "dpop_pds_nonce": oauth_session.dpop_pds_nonce or "",
         }
         return oauth_session.did, oauth_session.handle, session_data
     except Exception as e:

src/relay/config.py

···
     # app settings
     app_name: str = "relay"
     debug: bool = False
+    port: int = Field(default=8001, description="Server port")
 
     # database
     database_url: str = Field(
···
         description="Redis connection string",
     )
 
+    # storage
+    storage_backend: str = Field(default="filesystem", description="Storage backend (filesystem or r2)")
+
     # cloudflare r2
-    r2_account_id: str = Field(default="", description="Cloudflare R2 account ID")
-    r2_access_key_id: str = Field(default="", description="R2 access key ID")
-    r2_secret_access_key: str = Field(default="", description="R2 secret access key")
-    r2_bucket_name: str = Field(default="relay-audio", description="R2 bucket name")
-    r2_endpoint_url: str = Field(
-        default="",
-        description="R2 endpoint URL (computed from account_id if not provided)",
-    )
+    aws_access_key_id: str = Field(default="", description="AWS access key ID")
+    aws_secret_access_key: str = Field(default="", description="AWS secret access key")
+    r2_bucket: str = Field(default="", description="R2 bucket name")
+    r2_endpoint_url: str = Field(default="", description="R2 endpoint URL")
+    r2_public_bucket_url: str = Field(default="", description="R2 public bucket URL")
 
     # atproto
     atproto_pds_url: str = Field(
···
         default="http://localhost:8000/auth/callback",
         description="OAuth redirect URI",
     )
-
-    @property
-    def r2_endpoint(self) -> str:
-        """get r2 endpoint url."""
-        if self.r2_endpoint_url:
-            return self.r2_endpoint_url
-        return f"https://{self.r2_account_id}.r2.cloudflarestorage.com"
 
 
 settings = Settings()

src/relay/main.py

···
         "client_name": "relay",
         "client_uri": client_uri,
         "redirect_uris": [settings.atproto_redirect_uri],
-        "scope": "atproto",
+        "scope": "atproto repo:app.relay.track",
         "grant_types": ["authorization_code", "refresh_token"],
         "response_types": ["code"],
         "token_endpoint_auth_method": "none",

src/relay/models/__init__.py

···
 
 from relay.models.audio import AudioFormat
 from relay.models.database import Base, get_db, init_db
+from relay.models.session import UserSession
 from relay.models.track import Track
 
-__all__ = ["AudioFormat", "Base", "Track", "get_db", "init_db"]
+__all__ = ["AudioFormat", "Base", "Track", "UserSession", "get_db", "init_db"]

src/relay/models/database.py

···
 from sqlalchemy import create_engine
 from sqlalchemy.orm import DeclarativeBase, sessionmaker
 
-# sqlite database in local data directory
-DATABASE_URL = "sqlite:///./data/relay.db"
+from relay.config import settings
 
-engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
+# use postgres from settings (neon or local)
+engine = create_engine(settings.database_url)
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
 

src/relay/models/session.py

···
+"""session model for storing user sessions."""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from relay.models.database import Base
+
+
+class UserSession(Base):
+    """user session model."""
+
+    __tablename__ = "user_sessions"
+
+    session_id: Mapped[str] = mapped_column(String(64), primary_key=True, index=True)
+    did: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    handle: Mapped[str] = mapped_column(String, nullable=False)
+    oauth_session_data: Mapped[str] = mapped_column(
+        Text, nullable=False
+    )  # JSON stored as text
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        nullable=False,
+    )
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)

src/relay/models/track.py

···
 from datetime import datetime
 
 from sqlalchemy import DateTime, Integer, String
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 
 from relay.models.database import Base
 
 
 class Track(Base):
-    """track model."""
+    """track model.
+
+    only essential fields are explicit columns.
+    use metadata JSONB for flexible fields that may evolve.
+    """
 
     __tablename__ = "tracks"
 
+    # essential fields
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     title: Mapped[str] = mapped_column(String, nullable=False)
     artist: Mapped[str] = mapped_column(String, nullable=False)
-    album: Mapped[str | None] = mapped_column(String, nullable=True)
-    duration: Mapped[int | None] = mapped_column(Integer, nullable=True)  # seconds
     file_id: Mapped[str] = mapped_column(String, nullable=False, unique=True)
-    file_type: Mapped[str] = mapped_column(String, nullable=False)  # mp3 or wav
+    file_type: Mapped[str] = mapped_column(String, nullable=False)
     artist_did: Mapped[str] = mapped_column(String, nullable=False, index=True)
     artist_handle: Mapped[str] = mapped_column(String, nullable=False)
     created_at: Mapped[datetime] = mapped_column(
···
         default=datetime.utcnow,
         nullable=False,
     )
+
+    # flexible extra fields (album, duration, genre, etc.)
+    extra: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict, server_default="{}")
+
+    # ATProto integration fields
+    r2_url: Mapped[str | None] = mapped_column(String, nullable=True)
+    atproto_record_uri: Mapped[str | None] = mapped_column(String, nullable=True)
+    atproto_record_cid: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    @property
+    def album(self) -> str | None:
+        """get album from extra."""
+        return self.extra.get("album")
+
+    @property
+    def duration(self) -> int | None:
+        """get duration from extra (in seconds)."""
+        return self.extra.get("duration")

src/relay/storage/__init__.py

···
 """storage implementations."""
 
-from relay.storage.filesystem import FilesystemStorage, storage
+from relay.config import settings
+
+if settings.storage_backend == "r2":
+    from relay.storage.r2 import R2Storage
+
+    storage = R2Storage()
+else:
+    from relay.storage.filesystem import FilesystemStorage
 
-__all__ = ["FilesystemStorage", "storage"]
+    storage = FilesystemStorage()
+
+__all__ = ["storage"]

src/relay/storage/r2.py

···
+"""cloudflare R2 storage for audio files."""
+
+import hashlib
+from pathlib import Path
+from typing import BinaryIO
+
+import boto3
+from botocore.config import Config
+
+from relay.config import settings
+from relay.models import AudioFormat
+
+
+class R2Storage:
+    """store audio files on cloudflare R2."""
+
+    def __init__(self):
+        """initialize R2 client."""
+        if not all([
+            settings.r2_bucket,
+            settings.r2_endpoint_url,
+            settings.aws_access_key_id,
+            settings.aws_secret_access_key,
+        ]):
+            raise ValueError("R2 credentials not configured in environment")
+
+        self.bucket_name = settings.r2_bucket
+        self.public_bucket_url = settings.r2_public_bucket_url
+        self.client = boto3.client(
+            "s3",
+            endpoint_url=settings.r2_endpoint_url,
+            aws_access_key_id=settings.aws_access_key_id,
+            aws_secret_access_key=settings.aws_secret_access_key,
+            config=Config(
+                request_checksum_calculation="WHEN_REQUIRED",
+                response_checksum_validation="WHEN_REQUIRED",
+            ),
+        )
+
+    def save(self, file: BinaryIO, filename: str) -> str:
+        """save audio file to R2 and return file id."""
+        # read file content
+        content = file.read()
+
+        # generate file id from content hash
+        file_id = hashlib.sha256(content).hexdigest()[:16]
+
+        # determine file extension
+        ext = Path(filename).suffix.lower()
+        audio_format = AudioFormat.from_extension(ext)
+        if not audio_format:
+            raise ValueError(
+                f"unsupported file type: {ext}. "
+                f"supported: {AudioFormat.supported_extensions_str()}"
+            )
+
+        # construct s3 key
+        key = f"audio/{file_id}{ext}"
+
+        # upload to R2
+        self.client.put_object(
+            Bucket=self.bucket_name,
+            Key=key,
+            Body=content,
+            ContentType=audio_format.media_type,
+        )
+
+        return file_id
+
+    def get_url(self, file_id: str) -> str | None:
+        """get public URL for audio file."""
+        # try to find file with any supported extension
+        for audio_format in AudioFormat:
+            key = f"audio/{file_id}{audio_format.extension}"
+
+            # check if object exists
+            try:
+                self.client.head_object(Bucket=self.bucket_name, Key=key)
+                # object exists, return public URL
+                return f"{self.public_bucket_url}/{key}"
+            except self.client.exceptions.ClientError:
+                continue
+
+        return None
+
+    def delete(self, file_id: str) -> bool:
+        """delete audio file from R2."""
+        for audio_format in AudioFormat:
+            key = f"audio/{file_id}{audio_format.extension}"
+
+            try:
+                self.client.delete_object(Bucket=self.bucket_name, Key=key)
+                return True
+            except self.client.exceptions.ClientError:
+                continue
+
+        return False

tests/test_r2_upload.py

···
+"""test R2 upload functionality."""
+
+import shutil
+from pathlib import Path
+
+from relay.storage import storage
+from relay.storage.r2 import R2Storage
+
+
+def test_r2_upload():
+    """test uploading a file to R2 and retrieving its URL."""
+    # copy existing test file
+    source = Path("data/audio/f6197e825152d2b5.m4a")
+    test_dir = Path("tests/fixtures")
+    test_dir.mkdir(parents=True, exist_ok=True)
+    test_file = test_dir / "test_audio.m4a"
+    shutil.copy(source, test_file)
+
+    print(f"test file created: {test_file}")
+    print(f"file size: {test_file.stat().st_size} bytes")
+
+    # verify we're using R2 storage
+    assert isinstance(storage, R2Storage), f"expected R2Storage, got {type(storage)}"
+    print(f"✓ using R2 storage")
+
+    # upload file
+    with open(test_file, "rb") as f:
+        file_id = storage.save(f, "test_audio.m4a")
+
+    print(f"✓ uploaded file with id: {file_id}")
+
+    # get URL
+    url = storage.get_url(file_id)
+    print(f"✓ got public URL: {url}")
+
+    # verify URL format
+    assert url is not None
+    assert url.startswith("https://")
+    assert "r2.dev" in url
+    assert file_id in url
+
+    print("\n✓ all tests passed!")
+    print(f"\nfile is accessible at: {url}")
+
+    # cleanup
+    test_file.unlink()
+    test_dir.rmdir()
+
+
+if __name__ == "__main__":
+    test_r2_upload()

uv.lock

···
 version = 1
 revision = 3
 requires-python = ">=3.11"
+resolution-markers = [
+    "python_full_version >= '3.13'",
+    "python_full_version == '3.12.*'",
+    "python_full_version < '3.12'",
+]
 
 [[package]]
 name = "alembic"
···
 
 [[package]]
 name = "atproto"
-version = "0.0.1.dev460"
-source = { git = "https://github.com/zzstoatzz/atproto?rev=main#efe6f7407ae7edb7f35b410a1eb8dba7a5c63e7f" }
+version = "0.0.1.dev461"
+source = { git = "https://github.com/zzstoatzz/atproto?rev=main#57bb99a28c916a5b5c960ade00e4f82695860af1" }
 dependencies = [
     { name = "click" },
     { name = "cryptography" },
···
 ]
 
 [[package]]
+name = "psycopg"
+version = "3.2.12"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a8/77/c72d10262b872617e509a0c60445afcc4ce2cd5cd6bc1c97700246d69c85/psycopg-3.2.12.tar.gz", hash = "sha256:85c08d6f6e2a897b16280e0ff6406bef29b1327c045db06d21f364d7cd5da90b", size = 160642, upload-time = "2025-10-26T00:46:03.045Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c8/28/8c4f90e415411dc9c78d6ba10b549baa324659907c13f64bfe3779d4066c/psycopg-3.2.12-py3-none-any.whl", hash = "sha256:8a1611a2d4c16ae37eada46438be9029a35bb959bb50b3d0e1e93c0f3d54c9ee", size = 206765, upload-time = "2025-10-26T00:10:42.173Z" },
+]
+
+[package.optional-dependencies]
+binary = [
+    { name = "psycopg-binary", marker = "implementation_name != 'pypy'" },
+]
+
+[[package]]
+name = "psycopg-binary"
+version = "3.2.12"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/4d/980fdd0f75914c8b1f229a6e5a9c422b53e809166b96a7d0e1287b369796/psycopg_binary-3.2.12-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:16db2549a31ccd4887bef05570d95036813ce25fd9810b523ba1c16b0f6cfd90", size = 4037686, upload-time = "2025-10-26T00:16:22.041Z" },
+    { url = "https://files.pythonhosted.org/packages/51/76/6b6ccd3fd31c67bec8608225407322f26a2a633c05b35c56b7c0638dcc67/psycopg_binary-3.2.12-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:7b9a99ded7d19b24d3b6fa632b58e52bbdecde7e1f866c3b23d0c27b092af4e3", size = 4098526, upload-time = "2025-10-26T00:16:58.395Z" },
+    { url = "https://files.pythonhosted.org/packages/91/d8/be5242efed4f57f74a27eb47cb3a01bebb04e43ca57e903fcbda23361e72/psycopg_binary-3.2.12-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:385c7b5cfffac115f413b8e32c941c85ea0960e0b94a6ef43bb260f774c54893", size = 4646680, upload-time = "2025-10-26T00:17:36.967Z" },
+    { url = "https://files.pythonhosted.org/packages/20/c1/96e42d39c0e75c4059f80e8fc9b286e2b6d9652f30b42698101d4be201cf/psycopg_binary-3.2.12-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:9c674887d1e0d4384c06c822bc7fcfede4952742e232ec1e76b5a6ae39a3ddd4", size = 4749345, upload-time = "2025-10-26T00:18:16.61Z" },
+    { url = "https://files.pythonhosted.org/packages/78/00/0ee41e18bdb05b43a27ebf8a952343319554cd9bde7931f633343b5abbad/psycopg_binary-3.2.12-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:72fd979e410ba7805462817ef8ed6f37dd75f9f4ae109bdb8503e013ccecb80b", size = 4432535, upload-time = "2025-10-26T00:18:53.823Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/77/580cc455ba909d9e3082b80bb1952f67c5b9692a56ecaf71816ce0e9aa69/psycopg_binary-3.2.12-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ec82fa5134517af44e28a30c38f34384773a0422ffd545fd298433ea9f2cc5a9", size = 3888888, upload-time = "2025-10-26T00:19:26.768Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/29/0d0d2aa4238fd57ddbd2f517c58cefb26d408d3e989cbca9ad43f4c48433/psycopg_binary-3.2.12-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:100fdfee763d701f6da694bde711e264aca4c2bc84fb81e1669fb491ce11d219", size = 3571385, upload-time = "2025-10-26T00:19:56.844Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/7d/eb11cd86339122c19c1039cb5ee5f87f88d6015dff564b1ed23d0c4a90e7/psycopg_binary-3.2.12-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:802bd01fb18a0acb0dea491f69a9a2da6034f33329a62876ab5b558a1fb66b45", size = 3614219, upload-time = "2025-10-26T00:20:27.135Z" },
+    { url = "https://files.pythonhosted.org/packages/65/02/dff51dc1f88d9854405013e2cabbf7060c2b3993cb82d6e8ad21396081af/psycopg_binary-3.2.12-cp311-cp311-win_amd64.whl", hash = "sha256:f33c9e12ed05e579b7fb3c8fdb10a165f41459394b8eb113e7c377b2bd027f61", size = 2919778, upload-time = "2025-10-26T00:20:51.974Z" },
+    { url = "https://files.pythonhosted.org/packages/db/4a/b2779f74fdb0d661febe802fb3b770546a99f0a513ef108e8f9ed36b87cb/psycopg_binary-3.2.12-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ea9751310b840186379c949ede5a5129b31439acdb929f3003a8685372117ed8", size = 4019926, upload-time = "2025-10-26T00:21:25.599Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/af/df6c2beb44de456c4f025a61dfe611cf5b3eb3d3fa671144ce19ac7f1139/psycopg_binary-3.2.12-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:9fdf3a0c24822401c60c93640da69b3dfd4d9f29c3a8d797244fe22bfe592823", size = 4092107, upload-time = "2025-10-26T00:22:00.043Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/3b/b16260c93a0a435000fd175f1abb8d12af5542bd9d35d17dd2b7f347dbd5/psycopg_binary-3.2.12-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:49582c3b6d578bdaab2932b59f70b1bd93351ed4d594b2c97cea1611633c9de1", size = 4626849, upload-time = "2025-10-26T00:22:38.606Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/52/2c8d1c534777176e3e4832105f0b2f70c0ff3d63def0f1fda46833cc2dc1/psycopg_binary-3.2.12-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:5b6e505618cb376a7a7d6af86833a8f289833fe4cc97541d7100745081dc31bd", size = 4719811, upload-time = "2025-10-26T00:23:18.23Z" },
+    { url = "https://files.pythonhosted.org/packages/34/44/005ab6a42698489310f52f287b78c26560aeedb091ba12f034acdff4549b/psycopg_binary-3.2.12-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:6a898717ab560db393355c6ecf39b8c534f252afc3131480db1251e061090d3a", size = 4410950, upload-time = "2025-10-26T00:23:55.532Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/ba/c59303ed65659cd62da2b3f4ad2b8635ae10eb85e7645d063025277c953d/psycopg_binary-3.2.12-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bfd632f7038c76b0921f6d5621f5ba9ecabfad3042fa40e5875db11771d2a5de", size = 3861578, upload-time = "2025-10-26T00:24:28.482Z" },
+    { url = "https://files.pythonhosted.org/packages/29/ce/d36f03b11959978b2c2522c87369fa8d75c1fa9b311805b39ce7678455ae/psycopg_binary-3.2.12-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:3e9c9e64fb7cda688e9488402611c0be2c81083664117edcc709d15f37faa30f", size = 3534948, upload-time = "2025-10-26T00:24:58.657Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/cc/e0e5fc0d5f2d2650f85540cebd0d047e14b0933b99f713749b2ebc031047/psycopg_binary-3.2.12-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3c1e38b1eda54910628f68448598139a9818973755abf77950057372c1fe89a6", size = 3583525, upload-time = "2025-10-26T00:25:28.731Z" },
+    { url = "https://files.pythonhosted.org/packages/13/27/e2b1afb9819835f85f1575f07fdfc871dd8b4ea7ed8244bfe86a2f6d6566/psycopg_binary-3.2.12-cp312-cp312-win_amd64.whl", hash = "sha256:77690f0bf08356ca00fc357f50a5980c7a25f076c2c1f37d9d775a278234fefd", size = 2910254, upload-time = "2025-10-26T00:25:53.335Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/0b/9d480aba4a4864832c29e6fc94ddd34d9927c276448eb3b56ffe24ed064c/psycopg_binary-3.2.12-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:442f20153415f374ae5753ca618637611a41a3c58c56d16ce55f845d76a3cf7b", size = 4017829, upload-time = "2025-10-26T00:26:27.031Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/f3/0d294b30349bde24a46741a1f27a10e8ab81e9f4118d27c2fe592acfb42a/psycopg_binary-3.2.12-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:79de3cc5adbf51677009a8fda35ac9e9e3686d5595ab4b0c43ec7099ece6aeb5", size = 4089835, upload-time = "2025-10-26T00:27:01.392Z" },
+    { url = "https://files.pythonhosted.org/packages/82/d4/ff82e318e5a55d6951b278d3af7b4c7c1b19344e3a3722b6613f156a38ea/psycopg_binary-3.2.12-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:095ccda59042a1239ac2fefe693a336cb5cecf8944a8d9e98b07f07e94e2b78d", size = 4625474, upload-time = "2025-10-26T00:27:40.34Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/e8/2c9df6475a5ab6d614d516f4497c568d84f7d6c21d0e11444468c9786c9f/psycopg_binary-3.2.12-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:efab679a2c7d1bf7d0ec0e1ecb47fe764945eff75bb4321f2e699b30a12db9b3", size = 4720350, upload-time = "2025-10-26T00:28:20.104Z" },
+    { url = "https://files.pythonhosted.org/packages/74/f5/7aec81b0c41985dc006e2d5822486ad4b7c2a1a97a5a05e37dc2adaf1512/psycopg_binary-3.2.12-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d369e79ad9647fc8217cbb51bbbf11f9a1ffca450be31d005340157ffe8e91b3", size = 4411621, upload-time = "2025-10-26T00:28:59.104Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/15/d3cb41b8fa9d5f14320ab250545fbb66f9ddb481e448e618902672a806c0/psycopg_binary-3.2.12-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:eedc410f82007038030650aa58f620f9fe0009b9d6b04c3dc71cbd3bae5b2675", size = 3863081, upload-time = "2025-10-26T00:29:31.235Z" },
+    { url = "https://files.pythonhosted.org/packages/69/8a/72837664e63e3cd3aa145cedcf29e5c21257579739aba78ab7eb668f7d9c/psycopg_binary-3.2.12-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f3bae4be7f6781bf6c9576eedcd5e1bb74468126fa6de991e47cdb1a8ea3a42a", size = 3537428, upload-time = "2025-10-26T00:30:01.465Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/7e/1b78ae38e7d69e6d7fb1e2dcce101493f5fa429480bac3a68b876c9b1635/psycopg_binary-3.2.12-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8ffe75fe6be902dadd439adf4228c98138a992088e073ede6dd34e7235f4e03e", size = 3585981, upload-time = "2025-10-26T00:30:31.635Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/f8/245b4868b2dac46c3fb6383b425754ae55df1910c826d305ed414da03777/psycopg_binary-3.2.12-cp313-cp313-win_amd64.whl", hash = "sha256:2598d0e4f2f258da13df0560187b3f1dfc9b8688c46b9d90176360ae5212c3fc", size = 2912929, upload-time = "2025-10-26T00:30:56.413Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/5b/76fbb40b981b73b285a00dccafc38cf67b7a9b3f7d4f2025dda7b896e7ef/psycopg_binary-3.2.12-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:dc68094e00a5a7e8c20de1d3a0d5e404a27f522e18f8eb62bbbc9f865c3c81ef", size = 4016868, upload-time = "2025-10-26T00:31:29.974Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/08/8841ae3e2d1a3228e79eaaf5b7f991d15f0a231bb5031a114305b19724b1/psycopg_binary-3.2.12-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:2d55009eeddbef54c711093c986daaf361d2c4210aaa1ee905075a3b97a62441", size = 4090508, upload-time = "2025-10-26T00:32:04.192Z" },
+    { url = "https://files.pythonhosted.org/packages/05/de/a41f62230cf4095ae4547eceada218cf28c17e7f94376913c1c8dde9546f/psycopg_binary-3.2.12-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:66a031f22e4418016990446d3e38143826f03ad811b9f78f58e2afbc1d343f7a", size = 4629788, upload-time = "2025-10-26T00:32:43.28Z" },
+    { url = "https://files.pythonhosted.org/packages/45/19/529d92134eae44475f781a86d58cdf3edd0953e17c69762abf387a9f2636/psycopg_binary-3.2.12-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:58ed30d33c25d7dc8d2f06285e88493147c2a660cc94713e4b563a99efb80a1f", size = 4724124, upload-time = "2025-10-26T00:33:22.594Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/f5/97344e87065f7c9713ce213a2cff7732936ec3af6622e4b2a88715a953f2/psycopg_binary-3.2.12-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:e0b5ccd03ca4749b8f66f38608ccbcb415cbd130d02de5eda80d042b83bee90e", size = 4411340, upload-time = "2025-10-26T00:34:00.759Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/c2/34bce068f6bfb4c2e7bb1187bb64a3f3be254702b158c4ad05eacc0055cf/psycopg_binary-3.2.12-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:909de94de7dd4d6086098a5755562207114c9638ec42c52d84c8a440c45fe084", size = 3867815, upload-time = "2025-10-26T00:34:33.181Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/a1/c647e01ab162e6bfa52380e23e486215e9d28ffd31e9cf3cb1e9ca59008b/psycopg_binary-3.2.12-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:7130effd0517881f3a852eff98729d51034128f0737f64f0d1c7ea8343d77bd7", size = 3541756, upload-time = "2025-10-26T00:35:08.622Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/d0/795bdaa8c946a7b7126bf7ca8d4371eaaa613093e3ec341a0e50f52cbee2/psycopg_binary-3.2.12-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:89b3c5201ca616d69ca0c3c0003ca18f7170a679c445c7e386ebfb4f29aa738e", size = 3587950, upload-time = "2025-10-26T00:35:41.183Z" },
+    { url = "https://files.pythonhosted.org/packages/53/cf/10c3e95827a3ca8af332dfc471befec86e15a14dc83cee893c49a4910dad/psycopg_binary-3.2.12-cp314-cp314-win_amd64.whl", hash = "sha256:48a8e29f3e38fcf8d393b8fe460d83e39c107ad7e5e61cd3858a7569e0554a39", size = 3005787, upload-time = "2025-10-26T00:36:06.783Z" },
+]
+
+[[package]]
 name = "ptyprocess"
 version = "0.7.0"
 source = { registry = "https://pypi.org/simple" }
···
     { name = "fastapi" },
     { name = "httpx" },
     { name = "passlib", extra = ["bcrypt"] },
+    { name = "psycopg", extra = ["binary"] },
     { name = "pydantic" },
     { name = "pydantic-settings" },
     { name = "python-dotenv" },
···
     { name = "fastapi", specifier = ">=0.115.0" },
     { name = "httpx", specifier = ">=0.28.0" },
     { name = "passlib", extras = ["bcrypt"], specifier = ">=1.7.4" },
+    { name = "psycopg", extras = ["binary"], specifier = ">=3.2.12" },
     { name = "pydantic", specifier = ">=2.11.0" },
     { name = "pydantic-settings", specifier = ">=2.7.0" },
     { name = "python-dotenv", specifier = ">=1.1.0" },
···
 sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" }
 wheels = [
     { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
+]
+
+[[package]]
+name = "tzdata"
+version = "2025.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/32/1a225d6164441be760d75c2c42e2780dc0873fe382da3e98a2e1e48361e5/tzdata-2025.2.tar.gz", hash = "sha256:b60a638fcc0daffadf82fe0f57e53d06bdec2f36c4df66280ae79bce6bd6f2b9", size = 196380, upload-time = "2025-03-23T13:54:43.652Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5c/23/c7abc0ca0a1526a0774eca151daeb8de62ec457e77262b66b359c3c7679e/tzdata-2025.2-py2.py3-none-any.whl", hash = "sha256:1a403fada01ff9221ca8044d701868fa132215d84beb92242d9acd2147f667a8", size = 347839, upload-time = "2025-03-23T13:54:41.845Z" },
 ]
 
 [[package]]