stonks-oracle/.kiro/steering/development-process.md

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