Skip to Content
ContributeBackendOverview

Backend Documentation

This section is about the Rhesis backend: a FastAPI application that exposes REST APIs, handles authentication and organizations, and coordinates work with PostgreSQL, Redis, and Celery workers. The service is written for Python 3.12+ and uses uv for dependencies (see apps/backend/pyproject.toml).

Running the API locally

The smoothest path is the rh CLI from the repository root. From there, run the steps below in order. The first command creates apps/backend/.env and apps/frontend/.env.local with sensible defaults for local Postgres and Redis ports, JWT placeholders, and related settings.

local-api.sh
# One-time: environment files
./rh dev init

# Start Postgres and Redis
./rh dev up

# Install deps (uv sync), migrate if configured, then serve on port 8080
./rh dev backend

./rh dev backend runs uv sync, then apps/backend/start.sh, which applies migrations when the database is configured and starts Uvicorn on port 8080.

If you prefer not to use rh, go to apps/backend, ensure .env is present, run uv sync, then ./start.sh. Set SKIP_MIGRATIONS=true if something else already applied migrations (for example in CI or a deployment pipeline).

Once the server is up, open interactive docs at http://localhost:8080/docs, or ReDoc and the OpenAPI JSON at /redoc and /openapi.json. A simple GET /health responds with {"status": "ok"}. Background processing is not started with the API alone; use ./rh dev worker from the repo root when you need Celery (details in Background tasks).

How the codebase is organized

HTTP routes live under app/routers/, with Pydantic types in app/schemas/ and SQLAlchemy models in app/models/. Shared database helpers sit in app/crud.py. Authentication and token handling are grouped under app/auth/ (see Authentication). Celery-related code is split between tasks/ (what runs in the worker), celery/ (app wiring), and worker.py at the package root. Database migrations are Alembic revisions under src/rhesis/backend/alembic/; start.sh runs them for local development when SQLALCHEMY_DB_HOST is set.

A trimmed view of apps/backend:

layout.txt
apps/backend/
├── pyproject.toml
├── start.sh                 # loads .env, runs migrations, starts the server
└── src/rhesis/backend/
  ├── app/
  │   ├── main.py
  │   ├── routers/
  │   ├── models/
  │   ├── schemas/
  │   ├── services/
  │   ├── auth/
  │   ├── utils/
  │   ├── database.py
  │   └── crud.py
  ├── alembic/
  ├── tasks/
  ├── celery/
  ├── metrics/
  ├── logging/
  └── worker.py

Tests and code quality

Automated tests are not inside apps/backend; they live in tests/backend and tests/notifications, wired through pyproject.toml in the backend project. From apps/backend you can run the suite with:

test.sh
cd apps/backend
uv run pytest ../../tests/backend/ -v

Formatting and linting use Ruff. The project’s conventions and exact commands are described in Development workflow; the usual pattern is uv run --all-groups ruff check . and uv run --all-groups ruff format . from apps/backend.

Configuration

Secrets and connection strings are environment-driven. For a structured list of variables, see Environment configuration and the central Environment variables reference. Local ./rh dev init output is a good template for values such as SQLALCHEMY_DATABASE_URL, Redis broker URLs, and JWT_SECRET_KEY.

Further reading

TestingGetting Started