Development Setup¶

This guide will help you set up a development environment for contributing to Routstr Core.

Prerequisites¶

Before you begin, ensure you have:

Python 3.11+ - Required for type hints and modern features
Git - For version control
Docker (optional) - For running integration tests
Make - For running development commands

Quick Start¶

1. Fork and Clone¶

First, fork the repository on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/routstr-core.git
cd routstr-core

2. Install uv¶

We use uv for fast, reliable Python package management:

# Using the installer script
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

# Or with Homebrew (macOS)
brew install uv

3. Set Up Environment¶

Run the setup command:

make setup

This will:

✅ Install uv if not present
✅ Create a virtual environment
✅ Install all dependencies
✅ Install dev tools (mypy, ruff, pytest)
✅ Install project in editable mode

4. Configure Environment¶

Create your environment file:

cp .env.example .env

Edit .env with your configuration:

# Minimum required for development
UPSTREAM_BASE_URL=https://api.openai.com/v1
UPSTREAM_API_KEY=your-api-key  # Optional for mock testing
ADMIN_PASSWORD=development-password
DATABASE_URL=sqlite+aiosqlite:///dev.db

5. Verify Installation¶

Run these commands to verify your setup:

# Check dependencies
make check-deps

# Run unit tests
make test-unit

# Start development server
make dev

Development Workflow¶

Running the Server¶

For development with auto-reload:

make dev
# Server starts at http://localhost:8000
# Auto-reloads on code changes

For production-like environment:

make run

Code Quality¶

Before committing, always run:

# Format code
make format

# Check linting
make lint

# Type checking
make type-check

# All checks at once
make check

Testing¶

Run different test suites:

# Unit tests only (fast)
make test-unit

# Integration tests with mocks
make test-integration

# All tests
make test

# With coverage report
make test-coverage

# Run specific test
uv run pytest tests/unit/test_auth.py::test_token_validation -v

Database Management¶

Work with database migrations:

# Create new migration
make db-migrate

# Apply migrations
make db-upgrade

# Rollback one migration
make db-downgrade

# View current revision
make db-current

Project Structure¶

Understanding the codebase:

routstr-core/
├── routstr/                    # Main package
│   ├── __init__.py            # Package initialization
│   ├── auth.py                # Authentication logic
│   ├── balance.py             # Balance management
│   ├── discovery.py           # Nostr discovery
│   ├── proxy.py               # Request proxying
│   ├── wallet.py              # Cashu wallet integration
│   │
│   ├── core/                  # Core modules
│   │   ├── admin.py          # Admin dashboard
│   │   ├── db.py             # Database models
│   │   ├── exceptions.py     # Custom exceptions
│   │   ├── logging.py        # Logging setup
│   │   ├── main.py           # FastAPI app
│   │   └── middleware.py     # HTTP middleware
│   │
│   └── payment/               # Payment processing
│       ├── cost_calculation.py # Cost logic
│       ├── helpers.py         # Utilities
│       ├── lnurl.py          # Lightning URLs
│       ├── models.py         # Model pricing
│       ├── price.py          # BTC pricing
│       └── x_cashu.py        # Cashu headers
│
├── tests/                     # Test suite
│   ├── unit/                 # Unit tests
│   └── integration/          # Integration tests
│
├── migrations/               # Database migrations
├── scripts/                  # Utility scripts
├── docs/                     # Documentation
│
├── Makefile                  # Dev commands
├── pyproject.toml           # Project config
└── compose.yml              # Docker setup

Common Tasks¶

Adding a New Endpoint¶

Create route in appropriate module
Add request/response models
Write unit tests
Update API documentation
Add integration tests

Example:

# In routstr/core/main.py or appropriate router
@app.get("/v1/stats")
async def get_stats(
    user: User = Depends(get_current_user)
) -> StatsResponse:
    """Get usage statistics for the current user."""
    # Implementation
    pass

Adding a Database Model¶

Define model in routstr/core/db.py
Create migration: make db-migrate
Review generated migration
Apply: make db-upgrade

Example:

class Transaction(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    api_key_id: int = Field(foreign_key="apikey.id")
    amount: int  # millisatoshis
    timestamp: datetime = Field(default_factory=datetime.utcnow)
    description: str

Writing Tests¶

Follow the AAA pattern:

async def test_balance_deduction():
    # Arrange
    api_key = await create_test_api_key(balance=1000)

    # Act
    result = await deduct_balance(api_key.key, amount=100)

    # Assert
    assert result.success
    assert result.new_balance == 900
    assert result.deducted == 100

Development Tools¶

Makefile Commands¶

Key commands for development:

make help         # Show all commands
make setup        # Initial setup
make dev          # Run dev server
make test         # Run all tests
make lint         # Check code style
make format       # Fix code style
make type-check   # Check types
make clean        # Clean temp files
make docker-build # Build Docker image

IDE Setup¶

VS Code¶

Recommended extensions:

Python
Pylance
Ruff
GitLens

Settings (.vscode/settings.json):

{
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.formatting.provider": "ruff",
    "python.analysis.typeCheckingMode": "strict",
    "editor.formatOnSave": true
}

PyCharm¶

Set Python interpreter to uv venv
Enable type checking
Configure Ruff as external tool
Set up file watchers for formatting

Debugging¶

Debug Server¶

# Run with debug logging
LOG_LEVEL=DEBUG make dev

# Or with debugger
uv run python -m debugpy --listen 5678 --wait-for-client \
    -m uvicorn routstr:fastapi_app --reload

Debug Tests¶

# Run specific test with output
uv run pytest tests/unit/test_auth.py -v -s

# With debugger
uv run pytest tests/unit/test_auth.py --pdb

Troubleshooting¶

Common Issues¶

Import Errors

# Ensure project is installed in editable mode
uv sync
uv pip install -e .

Database Errors

# Reset database
rm dev.db
make db-upgrade

Type Checking Fails

# Clear mypy cache
make clean
make type-check

Tests Fail Locally

# Ensure test dependencies are installed
uv sync --dev

# Check for leftover test data
rm -rf test_*.db

Getting Help¶

Check existing GitHub Issues
Ask in GitHub Discussions
Read the Architecture Guide

Next Steps¶

Now that you're set up:

Read the Architecture Overview
Check open issues
Start with a small contribution

Happy coding! 🚀