SwimTO - Cursor Rules

# SwimTO - Cursor Rules

## Workspace Configuration

**IMPORTANT**: This project is part of the `raolivei` workspace. Workspace-level configuration is managed in the `workspace-config` repository.

- **Port Assignments**: See `../workspace-config/ports/.env.ports` for assigned ports
  - Web: Port `5173` (Vite default)
  - API: Port `8000` (assigned to avoid conflicts)
  - PostgreSQL: Port `5432`, Redis: Port `6379`
- **Workspace Conventions**: See `../workspace-config/docs/PROJECT_CONVENTIONS.md`
- **Port Conflict Checker**: Run `../workspace-config/scripts/check-ports.sh` before starting services
- **Workspace Scripts**: Available in `../workspace-config/scripts/`

When starting services locally, always use the assigned ports from `workspace-config` to prevent conflicts with other projects.

## Project Overview

SwimTO aggregates and displays indoor community pool drop-in swim schedules for Toronto. Commercial/proprietary project.

**CLUSTER**: Deployed on the **`eldertree`** Raspberry Pi k3s cluster.

## Security Requirements

### ALWAYS USE HTTPS

- ✅ **Production**: ALL external-facing services MUST use HTTPS
- ✅ **OAuth/Authentication**: Google OAuth REQUIRES HTTPS (blocks private IPs and HTTP)
- ✅ **Development**:
  - Use `http://localhost:5173` for local desktop testing
  - Use ngrok/Cloudflare Tunnel for mobile/external testing: `https://abc123.ngrok-free.app`
- ✅ **Kubernetes Ingress**: All ingress resources MUST use TLS certificates
- ❌ **NEVER**: Use `http://192.168.x.x` or `http://10.x.x.x` for OAuth callbacks (Google blocks these)
- ❌ **NEVER**: Expose authentication endpoints over HTTP in production

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

## 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 PEP 8
- Use type hints for all functions
- Write docstrings (Google style)
- Use FastAPI dependency injection
- SQLAlchemy for database models
- Alembic for migrations

### TypeScript (Frontend)

- Use TypeScript strictly (avoid `any`)
- Prefer functional components with hooks
- Use TanStack Query for data fetching
- Tailwind CSS for styling
- Follow React best practices

### Git Workflow

**CRITICAL**: Create different branches for different work. Do not mix up work - each branch should focus on a single feature, fix, or task. Keep branches focused and separate.

**Branch Naming:**

- `feature/api/<name>` - Backend features
- `feature/web/<name>` - Frontend features
- `feature/pipeline/<name>` - Data pipeline
- `fix/<name>` - Bug fixes
- `infra/k8s/<name>` - Kubernetes changes
- `docs/<name>` - Documentation

**Commit Messages:**

- Use conventional commits: `feat(api):`, `fix(web):`, `docs:`
- Scope indicates component: `api`, `web`, `pipeline`, `k8s`

**Version Consistency:**

- **Git tag versions must match Docker image tag versions** - When creating a release, ensure the git tag (e.g., `v1.2.3`) matches the Docker image tag used in deployment manifests and Helm charts

**Image Changes:**

- **Any changes to Docker images must always update CHANGELOG.md** - This includes changes to Dockerfiles, base images, image tags in deployment manifests, or any other image-related modifications

**CHANGELOG Requirements:**

**ALWAYS update CHANGELOG.md when:**

- ✅ Adding new features (user-facing or internal)
- ✅ Fixing bugs or issues
- ✅ Changing behavior, UI, or UX
- ✅ Modifying Docker images, Dockerfiles, or deployment configs
- ✅ Making breaking changes or deprecations
- ✅ Updating dependencies that affect functionality

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

- Version header: `## [X.Y.Z] - YYYY-MM-DD`
- Categories: `Added`, `Changed`, `Fixed`, `Removed`, `Deprecated`, `Security`
- Each entry starts with a dash and describes the change clearly
- Link related PRs/issues when applicable

**Git Command Restrictions:**

- **Never run git commands at workspace root**: Always ensure you are in the project directory (`swimTO/`) before running any git commands. Never run git commands at `/Users/roliveira/WORKSPACE/raolivei`

### Kubernetes Manifests

- **Use Helm charts where applicable** - Prefer Helm charts over raw YAML manifests when suitable charts exist
- Namespace: `swimto`
- Resource naming: `swimto-<component>`
- Separate deployments: `api-deployment.yaml`, `web-deployment.yaml` (or use Helm charts)
- Use ConfigMaps for non-sensitive config
- Secrets stored in Vault (see `scripts/setup-vault-secrets.sh`)

### Docker Images & GitHub Container Registry (GHCR)

- **Image Locations**:
  - API: `ghcr.io/raolivei/swimto-api:<tag>`
  - Web: `ghcr.io/raolivei/swimto-web:<tag>`
- **Image Tagging**: GitHub Actions automatically creates multiple tags per push:
  - Push to `main`: Creates `main`, `latest`, `sha-<commit-hash>` tags
  - Push to `dev`: Creates `dev`, `sha-<commit-hash>` tags
  - Push git tag (e.g., `v1.0.1`): Creates `v1.0.1`, `1.0`, `sha-<commit-hash>` tags
- **When Images Are Pushed**: Only on pushes to `main`/`dev` branches or git tag pushes. PR builds test but don't push images.
- **Viewing Images**: Check https://github.com/users/raolivei/packages
- **Testing Images Locally**: Build and test Docker images locally before pushing to ensure they work correctly
- **Deployment**: Use `latest` tag for automatic updates, or specific version tags (e.g., `v1.0.1`) for production stability

## 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. **Use Helm charts where applicable** - Prefer Helm charts for deployments
3. Update manifests in `k8s/` (or Helm charts in `helm/` if using Helm)
4. Test: `kubectl apply -f k8s/ --dry-run=client` or `helm template` for Helm charts
5. Update `docs/DEPLOYMENT_PI.md` if needed

## 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 start in detached mode
docker-compose up -d
```

**Access:**

- Frontend: http://localhost:5173
- API: http://localhost:8000
- API Docs: http://localhost:8000/docs

**Benefits:**

- Consistent environment (matches production)
- Hot reload enabled via volume mounts
- No local Python/Node version conflicts
- Single command to start everything

See `../workspace-config/docs/DOCKER_COMPOSE_GUIDE.md` for complete guide.

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

### 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: Playwright tests in `apps/web/tests/e2e/`

## Testing Locally

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

### Starting Services

```bash
# Start all services
docker-compose up

# Start in detached mode (background)
docker-compose up -d

# Start specific services only
docker-compose up db redis api
```

### Verifying Services

```bash
# Check running containers
docker-compose ps

# View logs
docker-compose logs -f [service-name]

# Test API health endpoint
curl http://localhost:8000/health

# Test frontend
curl http://localhost:5173
```

### Hot Reload Verification

1. Make a small code change (e.g., add a comment)
2. Save the file
3. Check docker-compose logs - should see reload message
4. Refresh browser - changes should appear

### Common Issues & Solutions

**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  # Check health status

# Restart services
docker-compose restart [service-name]
```

**Hot reload not working:**

- Verify volume mounts in docker-compose.yml
- Check file permissions
- Ensure source code directory matches volume path

## Environment Variables

### Required for Docker Compose

Always source port assignments before running 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"
```

### Project-Specific Variables

See `.env.example` files in `apps/api/` and `apps/web/` for required variables.

## Database 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 Database

```bash
# PostgreSQL shell
docker-compose exec db psql -U postgres -d pools

# Redis CLI
docker-compose exec redis redis-cli
```

## Data Sources

- City of Toronto Open Data Portal
- Daily updates at 3:00 AM via CronJob
- See `data-pipeline/` for scraping logic

## Important Notes

- **Proprietary project** - All rights reserved
- Secrets managed via Vault (not in git)
- Mobile-first design (test on devices)
- Runs on Raspberry Pi k3s cluster

## Documentation

- `docs/LOCAL_DEVELOPMENT.md` - Setup guide
- `docs/API.md` - API reference
- `docs/CONTRIBUTING.md` - Development workflow
- `docs/DEPLOYMENT_PI.md` - Deployment guide