Contributing Guide¶

# 1. Set up development environment
./setup.sh                    # Generate .env and docker-compose.override.yml
uv sync --extra dev           # Install Python dependencies
cd frontend && npm install    # Install frontend dependencies

# 2. Install pre-commit hooks
pre-commit install
pre-commit install --hook-type pre-push

# 3. Start services
podman-compose -f docker-compose.prod.yml up -d postgres redis

# 4. Run validation
./scripts/validate.sh

git checkout -b feature/camera-grid-pagination  # Features
git checkout -b fix/websocket-reconnect         # Bug fixes
git checkout -b refactor/batch-aggregator       # Refactoring

git commit -m "feat(cameras): add pagination to camera list endpoint"
git commit -m "fix(websocket): handle reconnection on network failure"
git commit -m "test(events): add integration tests for event filtering"

./scripts/validate.sh           # Run before PR
git push -u origin feature/my-feature
gh pr create --title "feat: my feature (NEM-123)"

# Full validation (recommended before PRs)
./scripts/validate.sh

# Backend checks
uv run ruff check --fix backend/   # Lint and fix
uv run ruff format backend/        # Format
uv run mypy backend/               # Type check

# Frontend checks
cd frontend
npm run lint:fix                   # Lint and fix
npm run format                     # Format
npm run typecheck                  # Type check

# Run all pre-commit hooks
pre-commit run --all-files

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies
uv sync --extra dev              # Install all dev dependencies
uv sync --group lint             # Install only lint tools
uv sync --group test             # Install only test tools

# Add dependencies
uv add httpx                     # Production dependency
uv add --dev pytest-sugar        # Dev dependency

# Run commands
uv run pytest backend/tests/     # Run tests
uv run ruff check backend/       # Run linter

# Update lock file
uv lock                          # After editing pyproject.toml

# Backend unit tests (parallel)
uv run pytest backend/tests/unit/ -n auto --dist=worksteal

# Backend integration tests (serial)
uv run pytest backend/tests/integration/ -n0

# Frontend unit tests
cd frontend && npm test

# Frontend E2E tests
cd frontend && npx playwright test

# With coverage
uv run pytest backend/tests/ --cov=backend --cov-report=html

# Quick validation
./scripts/validate.sh

# Or run individually:
uv run pytest backend/tests/unit/ -n auto          # Unit tests
uv run pytest backend/tests/integration/ -n0       # Integration tests
cd frontend && npm test                            # Frontend tests
uv run mypy backend/                               # Type check
cd frontend && npm run typecheck                   # Frontend types
pre-commit run --all-files                         # All hooks

cd frontend && npx playwright test                 # E2E tests

backend/
  api/routes/       # FastAPI endpoints
  api/schemas/      # Pydantic schemas
  core/             # Infrastructure (config, database, redis)
  models/           # SQLAlchemy models
  services/         # Business logic
  tests/
    unit/           # Unit tests
    integration/    # Integration tests

frontend/
  src/
    components/     # React components
    hooks/          # Custom hooks
    services/       # API client
    types/          # TypeScript types
  tests/
    e2e/            # Playwright tests