Development workflow and conventions for SwimTO, a Toronto indoor pool schedule aggregator deployed on Raspberry Pi k3s
This skill has safety concerns that you should review before use. Some patterns were detected that may pose a risk.Safety score: 65/100.
KillerSkills scans all public content for safety. Use caution before installing or executing flagged content.
Complete development conventions and workflow for SwimTO, a commercial project aggregating Toronto indoor pool schedules.
SwimTO is deployed on the **eldertree** Raspberry Pi k3s cluster and follows strict workspace-level conventions for port management and development standards.
This project is part of the `raolivei` workspace with centralized configuration:
- Web: Port 5173 (Vite)
- API: Port 8000
- PostgreSQL: 5432, Redis: 6379
**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**:
```
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
```
Follow these standards:
Follow these standards:
**Branch Naming**:
**CRITICAL**: Create separate branches for different work. Never mix unrelated changes in one branch.
**Commit Messages**:
**Version Consistency**:
**Git Command Restrictions**:
**ALWAYS update CHANGELOG.md when**:
**Format**: Follow [Keep a Changelog](https://keepachangelog.com/):
**Image Locations**:
**Image Tagging** (automatic via GitHub Actions):
**When Images Are Pushed**:
**Best Practices**:
Start all services with hot reload:
```bash
source ../workspace-config/ports/.env.ports
docker-compose up
docker-compose up -d
```
**Access**:
**Benefits**:
```bash
cd apps/api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
cd apps/web
npm install
npm run dev
```
```bash
../workspace-config/scripts/check-ports.sh
docker ps
source ../workspace-config/ports/.env.ports
```
```bash
docker-compose ps
docker-compose logs -f [service-name]
curl http://localhost:8000/health
curl http://localhost:5173
```
1. Make a code change (add comment)
2. Save file
3. Check logs for reload message
4. Refresh browser - changes should appear
```bash
docker-compose exec api make test
docker-compose exec web npm test
cd apps/api && make test
cd apps/web && npm test
```
E2E tests in `apps/web/tests/e2e/` using Playwright.
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`
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
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
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
```bash
docker-compose exec api alembic upgrade head
docker-compose exec api alembic revision --autogenerate -m "description"
docker-compose exec api alembic downgrade -1
```
```bash
docker-compose exec db psql -U postgres -d pools
docker-compose exec redis redis-cli
```
```bash
lsof -i :<PORT>
kill -9 <PID>
```
```bash
docker-compose build --no-cache
docker-compose logs [service-name]
```
```bash
docker-compose ps
docker-compose restart [service-name]
```
Always source port assignments before docker-compose:
```bash
source ../workspace-config/ports/.env.ports
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.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/swimto-cursor-rules/raw