SwimTO - Cursor Rules

You are working on **SwimTO**, a commercial project that aggregates indoor community pool drop-in swim schedules for Toronto. This project is deployed on a **Raspberry Pi k3s cluster** (codename: `eldertree`) and follows strict workspace conventions.

Workspace Configuration

**CRITICAL**: This project is part of the `raolivei` workspace with centralized configuration.

Port Assignments

**Before starting services:**

```bash

source ../workspace-config/ports/.env.ports

../workspace-config/scripts/check-ports.sh

```

Project Structure

```

swimTO/

├── apps/

│ ├── api/ # FastAPI backend (Python)

│ └── web/ # React + Vite frontend (TypeScript)

├── data-pipeline/ # ETL and data discovery (Python)

├── k8s/ # Kubernetes manifests

├── scripts/ # Utility scripts

└── docs/ # Documentation

```

Security Requirements - ALWAYS USE HTTPS

**CRITICAL RULES:**

- Local desktop: `http://localhost:5173`

- Mobile/external testing: Use ngrok/Cloudflare Tunnel with HTTPS

**Valid OAuth Redirect URIs:**

```

✅ http://localhost:5173/auth/callback (local dev only)

✅ https://swimto.example.com/auth/callback (production)

✅ https://abc123.ngrok-free.app/auth/callback (mobile testing)

❌ http://192.168.2.48:5173/auth/callback (BLOCKED by Google)

```

Code Conventions

Python (Backend API)

1. Follow PEP 8 strictly

2. Use type hints for all functions

3. Write docstrings (Google style)

4. Use FastAPI dependency injection

5. SQLAlchemy for database models

6. Alembic for migrations

TypeScript (Frontend)

1. Use TypeScript strictly - avoid `any`

2. Prefer functional components with hooks

3. Use TanStack Query for data fetching

4. Tailwind CSS for styling

5. Follow React best practices

Git Workflow

**CRITICAL**: Create separate branches for different work. Never mix unrelated changes.

**Branch Naming:**

**Commit Messages:**

**Version Consistency:**

**CHANGELOG Requirements:**

**ALWAYS update CHANGELOG.md when:**

**Format** (Keep a Changelog style):

```markdown

[X.Y.Z] - YYYY-MM-DD

Added

Changed

Fixed

```

**Git Command Restrictions:**

Kubernetes Manifests

1. **Prefer Helm charts over raw YAML** when suitable charts exist

2. Namespace: `swimto`

3. Resource naming: `swimto-<component>`

4. Use ConfigMaps for non-sensitive config

5. Secrets stored in Vault (see `scripts/setup-vault-secrets.sh`)

Docker Images & GitHub Container Registry (GHCR)

**Image Locations:**

**Image Tagging** (automatic via GitHub Actions):

**Testing**: Always test Docker images locally before pushing.

**Deployment**: Use `latest` for auto-updates or specific version tags for production stability.

Development Setup

Recommended: Docker Compose (Primary Method)

```bash

Load port assignments

source ../workspace-config/ports/.env.ports

Start all services with hot reload

docker-compose up

Or detached mode

docker-compose up -d

```

**Access:**

Pre-flight Checks

```bash

1. Check port conflicts

../workspace-config/scripts/check-ports.sh

2. Ensure Docker is running

docker ps

3. Load port assignments

source ../workspace-config/ports/.env.ports

```

Verifying Services

```bash

Check containers

docker-compose ps

View logs

docker-compose logs -f [service-name]

Test API health

curl http://localhost:8000/health

Test frontend

curl http://localhost:5173

```

Testing

```bash

With docker-compose (recommended)

docker-compose exec api make test

docker-compose exec web npm test

E2E tests

cd apps/web && npx playwright test

```

Database Migrations

```bash

Run migrations

docker-compose exec api alembic upgrade head

Create new migration

docker-compose exec api alembic revision --autogenerate -m "description"

Rollback

docker-compose exec api alembic downgrade -1

Access database

docker-compose exec db psql -U postgres -d pools

docker-compose exec redis redis-cli

```

Common Tasks

Adding API Endpoint

1. Create branch: `feature/api/add-endpoint`

2. Add route in `apps/api/app/routes/`

3. Add schema in `apps/api/app/schemas.py`

4. Add tests in `apps/api/tests/`

5. Update `docs/API.md`

6. Update CHANGELOG.md

Adding Frontend Component

1. Create branch: `feature/web/add-component`

2. Create component in `apps/web/src/components/`

3. Add types in `apps/web/src/types/`

4. Add tests if needed

5. Export from index if reusable

6. Update CHANGELOG.md

Updating Data Pipeline

1. Create branch: `feature/pipeline/update-scraper`

2. Update scripts in `data-pipeline/`

3. Test locally with sample data

4. Update CronJob manifest if schedule changes

5. Update CHANGELOG.md

Kubernetes Deployment

1. Create branch: `infra/k8s/update-deployment`

2. **Prefer Helm charts** where applicable

3. Update manifests in `k8s/` (or Helm charts in `helm/`)

4. Test: `kubectl apply -f k8s/ --dry-run=client` or `helm template`

5. Update `docs/DEPLOYMENT_PI.md` if needed

6. Update CHANGELOG.md

Common Issues & Solutions

**Port conflicts:**

```bash

lsof -i :<PORT>

kill -9 <PID>

```

**Container won't start:**

```bash

docker-compose build --no-cache

docker-compose logs [service-name]

```

**Database connection issues:**

```bash

docker-compose ps # Check health status

docker-compose restart [service-name]

```

**Hot reload not working:**

Important Notes

Documentation