Development Workflow

Recommended day-to-day workflow for the backend.

Local Development Setup

Initial Setup

1. Clone the repository
2. Set up your Python environment (Python 3.10+)
3. Install dependencies with UV: uv pip install -e .
4. Set up your local PostgreSQL database
5. Configure your .env file with local settings

Running the Application

Start the FastAPI development server:

uvicorn rhesis.backend.app.main:app --reload

The --reload flag enables auto-reloading when code changes are detected.

Code Style and Quality

Formatting

The project uses ruff for code formatting. Format your code using:

uv run --all-groups ruff format .

This ensures consistent code style across the project.

Linting

Run the linter to check for code quality issues:

uv run --all-groups ruff check .

Fix automatically fixable issues:

uv run --all-groups ruff check --fix .

Type Checking

Type hints are encouraged for readability and IDE support; enforcement is not strict everywhere.

Database Changes

Creating Models

When creating new database models:

1. Define your model in app/models/
2. Import it in app/models/__init__.py
3. Create corresponding Pydantic schemas in app/schemas/
4. Add CRUD operations in app/crud.py

Database Migrations

For schema changes:

1. Make changes to your SQLAlchemy models
2. Generate a migration: alembic revision --autogenerate -m "Description of changes"
3. Review the generated migration file in alembic/versions/
4. Apply the migration: alembic upgrade head

API Development

Creating New Endpoints

When adding new API endpoints:

1. Create or modify a router file in app/routers/
2. Define your endpoint functions with appropriate decorators
3. Import and register your router in app/routers/__init__.py
4. Add necessary schemas, models, and CRUD operations

Testing Endpoints

Test your endpoints using:

1. FastAPI’s interactive documentation (Swagger UI) at /docs
2. API client tools like Postman or Insomnia
3. Automated tests (see Testing section)

Background Tasks

Creating Celery Tasks

When creating new background tasks:

1. Define your task in an appropriate file in tasks/
2. Import and register your task in tasks/__init__.py
3. Add any necessary database models and schemas

Testing Tasks

Test your tasks using:

1. Direct invocation in development mode
2. Running a local Celery worker: celery -A rhesis.backend.worker worker --loglevel=info

Testing

Writing Tests

Tests are located in the tests/backend/ directory. When writing tests:

1. Create test files that mirror the structure of the code being tested
2. Use pytest fixtures for common setup and teardown
3. Use a test database (configured in conftest.py)

Running Tests

Run the test suite:

pytest

Run specific tests:

pytest tests/backend/test_specific_module.py

Debugging

Logging

Use the application’s logging system for debugging:

from rhesis.backend.logging import logger

logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

Interactive Debugging

For interactive debugging:

1. Add breakpoints using breakpoint() or your IDE’s debugging tools
2. Run the application in debug mode through your IDE
3. Use print() statements judiciously for quick debugging

Git Workflow

Use short-lived branches from the integration branch your team uses, conventional commit messages (present tense, ~50-char subject), PRs with description and linked issues, and green tests before merge.

Deployment

See Deployment. Before release: tests green, dependency review if you bumped packages, env vars and migrations checked.

Troubleshooting

Typical issues: bad SQLALCHEMY_DATABASE_URL or Postgres not running, missing .env keys, wrong PYTHONPATH/venv, or JWT/auth misconfiguration. Check logs and Environment configuration.