SwimTO Cursor Rules

Complete development conventions and workflow for SwimTO, a commercial project aggregating Toronto indoor pool schedules.

Project Context

SwimTO is deployed on the **eldertree** Raspberry Pi k3s cluster and follows strict workspace-level conventions for port management and development standards.

Core Rules

Workspace Configuration

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

- Web: Port 5173 (Vite)

- API: Port 8000

- PostgreSQL: 5432, Redis: 6379

Security: HTTPS Requirements

**CRITICAL**: All external-facing services MUST use HTTPS.

**Production**:

**OAuth/Authentication**:

**Valid 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)

```

**Development**:

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

```

Code Conventions

Python (Backend API)

Follow these standards:

TypeScript (Frontend)

Follow these standards:

Git Workflow

**Branch Naming**:

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

**Commit Messages**:

**Version Consistency**:

**Git Command Restrictions**:

CHANGELOG Requirements

**ALWAYS update CHANGELOG.md when**:

**Format**: Follow [Keep a Changelog](https://keepachangelog.com/):

Docker Images & GHCR

**Image Locations**:

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

**When Images Are Pushed**:

**Best Practices**:

Kubernetes Manifests

Development Workflow

Recommended: Docker Compose (Primary Method)

Start all services with hot reload:

```bash

Load port assignments

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

Start all services

docker-compose up

Or detached mode

docker-compose up -d

```

**Access**:

**Benefits**:

Alternative: Local Development (Fallback)

```bash

Backend

cd apps/api

python -m venv venv

source venv/bin/activate

pip install -r requirements.txt

uvicorn app.main:app --reload

Frontend

cd apps/web

npm install

npm run dev

```

Pre-flight Checks

```bash

1. Check for 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 running 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

```

Hot Reload Verification

1. Make a code change (add comment)

2. Save file

3. Check logs for reload message

4. Refresh browser - changes should appear

Testing

```bash

With docker-compose (recommended)

docker-compose exec api make test

docker-compose exec web npm test

Or locally

cd apps/api && make test

cd apps/web && npm test

```

E2E tests in `apps/web/tests/e2e/` using Playwright.

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`

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

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

Kubernetes Deployment

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

2. Prefer Helm charts for deployments

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

Database Operations

Migrations with Docker Compose

```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

```

Accessing Databases

```bash

PostgreSQL shell

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

Redis CLI

docker-compose exec redis redis-cli

```

Troubleshooting

Port Conflicts

```bash

Find what's using a port

lsof -i :<PORT>

Kill process if needed

kill -9 <PID>

```

Container Won't Start

```bash

Rebuild containers

docker-compose build --no-cache

Check logs

docker-compose logs [service-name]

```

Database Connection Issues

```bash

Wait for health checks

docker-compose ps

Restart services

docker-compose restart [service-name]

```

Hot Reload Not Working

Environment Variables

Always source port assignments before docker-compose:

```bash

From project root

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

Or set WORKSPACE_CONFIG variable

export WORKSPACE_CONFIG="$HOME/WORKSPACE/raolivei/workspace-config"

source "$WORKSPACE_CONFIG/ports/.env.ports"

```

See `.env.example` files in `apps/api/` and `apps/web/` for project-specific variables.

Data Sources

Important Notes

Documentation