PoleDanceApp/CLAUDE.md

CLAUDE.md — Pole Dance Championships App

Target Vision

See dancechamp-claude-code/ for full spec (3-app Supabase platform). Current implementation is a simplified MVP working toward that goal.

Quick Start

# Backend
cd backend && .venv/Scripts/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Mobile (set BASE_URL in src/api/client.ts to LAN IP first)
cd mobile && npx expo start --lan --clear

# Seed test data
cd backend && .venv/Scripts/python seed.py

Current Architecture

• Backend: FastAPI + SQLAlchemy 2 (async) + aiosqlite (SQLite dev) + Alembic + bcrypt
• Mobile: Expo (blank-typescript) + React Navigation v6 + Zustand + Axios + Ionicons
• Auth: JWT access (15min) + refresh token rotation (7 days, SHA-256 hashed in DB)

Project Layout

backend/app/           FastAPI app (models, schemas, routers, crud, services)
backend/alembic/       Async migrations
backend/.venv/         Virtual env (use .venv/Scripts/python)
mobile/src/api/        Axios client + API modules (auth, championships, users)
mobile/src/store/      Zustand auth store
mobile/src/screens/    auth/, championships/, admin/, profile/
mobile/src/navigation/ RootNavigator -> AuthStack | AppStack (Tabs + Detail)
dancechamp-claude-code/ Target spec: SPEC.md, PLAN.md, DATABASE.md, DESIGN-SYSTEM.md, SCREENS.md

Gotchas

• passlib + bcrypt 5.x incompatible — use bcrypt directly (NOT passlib)
• Circular import: auth_service.py must NOT import crud_user
• SQLAlchemy UUID: Use sqlalchemy.Uuid(as_uuid=True) not postgresql.UUID
• Expo newArchEnabled: true crashes Expo Go — keep false in app.json
• Stale uvicorn: Kill with powershell.exe -NoProfile -Command "Get-Process python | Stop-Process -Force"
• BASE_URL: mobile/src/api/client.ts must use LAN IP (not localhost) for physical devices

Test Credentials (run seed.py)

admin@pole.dev / Admin1234       (admin, approved)
organizer@pole.dev / Org1234     (organizer, approved)
member@pole.dev / Member1234     (member, approved)

API Routes

• Auth: POST /api/v1/auth/{register,login,refresh,logout,me}
• Championships: GET/POST/PATCH/DELETE /api/v1/championships
• Registrations: POST/GET/PATCH/DELETE /api/v1/registrations
• Users (admin): GET /api/v1/users, PATCH /api/v1/users/{id}/{approve,reject}
• Health: GET /internal/health | Swagger: GET /docs

Code Conventions

• Backend: Pydantic v2 schemas, async SQLAlchemy, from_attributes = True
• Mobile: Functional components, Zustand stores, Ionicons for icons
• Registration: members auto-approved, organizers require admin approval
• Tab navigator uses headerShown: true for safe area; no manual headings in tab screens

Environment

• Windows 10, Python 3.12, Node.js
• Docker NOT installed, PostgreSQL NOT installed (use SQLite for dev)
• venv always in backend/.venv