# Development Process — Test-Develop-Debug

## Local Environment
- Python 3.12 via NixOS, virtualenv at `.venv/`
- Always use `.venv/bin/python` or activate with `source .venv/bin/activate` before running Python commands
- For tools not available in `.venv/` (ruff, gh, etc.), use `nix-shell -p <pkg> --run "<cmd>"`
- Node.js 24 for frontend; `frontend/` has its own `node_modules/`
- Frontend tests: `cd frontend && npx vitest --run`
- Python tests: `nix-shell -p ruff --run "ruff check services/"` then `python -m pytest tests/ -x --tb=short -q`

## Workflow
1. Write or update tests for the target behavior
2. Implement the minimal code to pass
3. Debug failures, fix, re-run
4. Commit and push — CI builds images automatically
5. Deploy: `helm upgrade --install stonks-oracle infra/helm/stonks-oracle -n stonks-oracle`
6. Restart changed services: `kubectl rollout restart deployment/<name> -n stonks-oracle`

## Testing
- Python: `pytest` with `pytest-asyncio` for async code, tests in `tests/`
- Frontend: Vitest + MSW (Mock Service Worker) for deterministic API mocking, tests in `frontend/src/test/`
- Run Python tests: `python -m pytest tests/ -x --tb=short -q`
- Run frontend tests: `cd frontend && npx vitest --run`
- Lint Python: `nix-shell -p ruff --run "ruff check services/"`

## CI/CD — GitHub Actions
- Workflow: `.github/workflows/build.yml`
- Triggers on push to `main` and PRs
- Jobs:
  - `lint-and-test`: ruff lint + pytest + frontend vitest (Node 24)
  - `build-services`: matrix build of all Python services → GHCR
  - `build-dashboard`: frontend/Dockerfile → GHCR
  - `build-superset`: docker/Dockerfile.superset → GHCR
- CI handles all image builds and pushes — do NOT manually docker push
- Check CI: `nix-shell -p gh --run "gh run list -L 3"`
- Re-run failed: `nix-shell -p gh --run "gh run rerun <id> --failed"`

## Deploy
- Full deploy/redeploy: `~/sources/kube/stonks-oracle/runmefirst.sh`
- Full teardown: `~/sources/kube/stonks-oracle/runmelast.sh`
- Quick Helm upgrade: `helm upgrade --install stonks-oracle infra/helm/stonks-oracle -n stonks-oracle`
- Restart single service: `kubectl rollout restart deployment/<name> -n stonks-oracle`
- Check pods: `kubectl get pods -n stonks-oracle`

## Git Conventions
- Commit after each completed phase task
- Commit message format: `phase N: short description`
- Push to `main` triggers CI

## Code Style
- Python 3.12, type hints everywhere
- Pydantic for data validation
- FastAPI for HTTP services
- asyncio + asyncpg/aioredis for async I/O
- Minimal dependencies, prefer stdlib where possible
- Frontend: React 19, TypeScript strict mode, Tailwind CSS, TanStack Router/Query
- UUID fields from asyncpg must be converted to str via `_row_dict()` helpers

## Documentation
- Do NOT create large summary/success markdown files after each step
- Keep notes short, concise, and organized under `docs/notes/`
- If a note isn't useful for future reference, don't write it