Development Setup¶

This guide covers local development workflows for the loryth-issues service.

Prerequisites¶

Python 3.13+
uv for dependency management
Docker & Docker Compose (for PostgreSQL and RabbitMQ)

Initial Setup¶

cd server/services/loryth-issues

# Create virtualenv and install all dependencies
make setup

# Start PostgreSQL, RabbitMQ, and run migrations
make docker-up

Running the Service¶

# Start with hot-reload (port 8000)
make dev

Testing¶

Tests are full integration tests using testcontainers (PostgreSQL). Docker must be running.

# Run the full test suite
make test

# Run a specific test
.venv/bin/python -m pytest tests/api/test_issues.py::test_name -v

Linting & Formatting¶

# Check linting (ruff + mypy)
make lint

# Auto-format code
make format

Database¶

# Start infrastructure containers + run migrations
make docker-up

# Stop containers and remove volumes
make docker-down

# Open a psql shell
make docker-db

Migrations are pure SQL files in the migrations/ directory (v00-v05).

Project Structure¶

loryth-issues/
├── migrations/         # SQL migration scripts
├── src/loryth/issues/
│   ├── api/            # FastAPI routers + Pydantic schemas
│   ├── config/         # DI container and app configuration
│   ├── domain/         # Aggregates, services, DTOs, events
│   ├── persistence/    # SQLAlchemy repositories
│   ├── worker/         # Background workers
│   └── cli/            # CLI commands
├── tests/              # Integration tests
└── pyproject.toml      # Project configuration (uv)