mirror of
https://github.com/Routstr/routstr-core.git
synced 2026-08-09 02:54:37 +00:00
425 lines
9.5 KiB
Markdown
425 lines
9.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/routstr-core.git
|
|
cd routstr-core
|
|
```
|
|
|
|
### 2. Set Up Environment
|
|
|
|
Run the setup command:
|
|
|
|
```bash
|
|
make setup
|
|
```
|
|
|
|
This will:
|
|
|
|
- ✅ Install [uv](https://github.com/astral-sh/uv) if not present
|
|
- ✅ Create a virtual environment
|
|
- ✅ Install all dependencies
|
|
- ✅ Install dev tools (mypy, ruff, pytest)
|
|
- ✅ Install project in editable mode
|
|
|
|
### 3. Configure Environment
|
|
|
|
Create your environment file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your configuration:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### 4. Verify Installation
|
|
|
|
Run these commands to verify your setup:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
make dev
|
|
# Server starts at http://localhost:8000
|
|
# Auto-reloads on code changes
|
|
```
|
|
|
|
For production-like environment:
|
|
|
|
```bash
|
|
make run
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
Before committing, always run:
|
|
|
|
```bash
|
|
# Format code
|
|
make format
|
|
|
|
# Check linting
|
|
make lint
|
|
|
|
# Type checking
|
|
make type-check
|
|
|
|
# All checks at once
|
|
make check
|
|
```
|
|
|
|
### Testing
|
|
|
|
Run different test suites:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
│ ├── algorithm.py # Provider selection algorithms
|
|
│ ├── auth.py # Authentication logic
|
|
│ ├── balance.py # Balance management API
|
|
│ ├── discovery.py # Nostr discovery
|
|
│ ├── lightning.py # Lightning invoice handling
|
|
│ ├── nip91.py # Node announcement implementation
|
|
│ ├── proxy.py # Request proxying
|
|
│ ├── wallet.py # Cashu wallet integration
|
|
│ │
|
|
│ ├── core/ # Core modules
|
|
│ │ ├── admin.py # Admin dashboard API
|
|
│ │ ├── db.py # Database models (SQLModel)
|
|
│ │ ├── exceptions.py # Custom exceptions
|
|
│ │ ├── log_manager.py # Log management
|
|
│ │ ├── logging.py # Logging setup
|
|
│ │ ├── main.py # FastAPI app entry
|
|
│ │ ├── middleware.py # HTTP middleware
|
|
│ │ └── settings.py # Configuration
|
|
│ │
|
|
│ ├── payment/ # Payment processing
|
|
│ │ ├── cost_calculation.py
|
|
│ │ ├── helpers.py
|
|
│ │ ├── lnurl.py # LNURL support
|
|
│ │ ├── models.py # Model pricing
|
|
│ │ └── price.py # BTC/USD rates
|
|
│ │
|
|
│ └── upstream/ # Upstream providers
|
|
│ ├── base.py # Base provider class
|
|
│ ├── helpers.py # Shared utilities
|
|
│ ├── openai.py # OpenAI
|
|
│ ├── anthropic.py # Anthropic
|
|
│ ├── gemini.py # Google Gemini
|
|
│ ├── openrouter.py # OpenRouter
|
|
│ └── ... # More providers
|
|
│
|
|
├── ui/ # Admin dashboard (Next.js)
|
|
│ ├── app/ # Next.js app router
|
|
│ │ ├── page.tsx # Landing page
|
|
│ │ ├── balances/ # Balance management
|
|
│ │ ├── logs/ # Request logs viewer
|
|
│ │ ├── model/ # Model configuration
|
|
│ │ ├── providers/ # Upstream providers
|
|
│ │ ├── settings/ # Node settings
|
|
│ │ └── transactions/ # Transaction history
|
|
│ ├── components/ # React components
|
|
│ │ ├── ui/ # shadcn/ui primitives
|
|
│ │ ├── landing/ # Landing page components
|
|
│ │ └── settings/ # Settings components
|
|
│ └── lib/ # Utilities & API client
|
|
│ ├── api/ # Backend API client
|
|
│ ├── auth/ # Auth context
|
|
│ └── hooks/ # React hooks
|
|
│
|
|
├── tests/ # Test suite
|
|
├── migrations/ # Alembic migrations
|
|
├── scripts/ # Utility scripts
|
|
├── docs/ # Documentation
|
|
├── examples/ # Usage examples
|
|
│
|
|
├── Makefile # Dev commands
|
|
├── pyproject.toml # Project config
|
|
└── compose.yml # Docker setup
|
|
```
|
|
|
|
### Admin Dashboard (UI)
|
|
|
|
The admin dashboard is a Next.js app using:
|
|
|
|
- **Next.js 14** with App Router
|
|
- **shadcn/ui** for components
|
|
- **Tailwind CSS** for styling
|
|
- **pnpm** for package management
|
|
|
|
```bash
|
|
# Development
|
|
cd ui
|
|
pnpm install
|
|
pnpm dev # http://localhost:3000
|
|
|
|
# Build for production
|
|
pnpm build
|
|
```
|
|
|
|
The UI is served by the FastAPI backend at `/admin/` when built. Use `make build-ui` to build and copy to the backend.
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Endpoint
|
|
|
|
1. Create route in appropriate module
|
|
2. Add request/response models
|
|
3. Write unit tests
|
|
4. Update API documentation
|
|
5. Add integration tests
|
|
|
|
Example:
|
|
|
|
```python
|
|
# 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
|
|
|
|
1. Define model in `routstr/core/db.py`
|
|
2. Create migration: `make db-migrate`
|
|
3. Review generated migration
|
|
4. Apply: `make db-upgrade`
|
|
|
|
Example:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```json
|
|
{
|
|
"python.linting.enabled": true,
|
|
"python.linting.ruffEnabled": true,
|
|
"python.formatting.provider": "ruff",
|
|
"python.analysis.typeCheckingMode": "strict",
|
|
"editor.formatOnSave": true
|
|
}
|
|
```
|
|
|
|
#### PyCharm
|
|
|
|
1. Set Python interpreter to uv venv
|
|
2. Enable type checking
|
|
3. Configure Ruff as external tool
|
|
4. Set up file watchers for formatting
|
|
|
|
### Debugging
|
|
|
|
#### Debug Server
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
# Ensure project is installed in editable mode
|
|
uv sync
|
|
uv pip install -e .
|
|
```
|
|
|
|
**Database Errors**
|
|
|
|
```bash
|
|
# Reset database
|
|
rm dev.db
|
|
make db-upgrade
|
|
```
|
|
|
|
**Type Checking Fails**
|
|
|
|
```bash
|
|
# Clear mypy cache
|
|
make clean
|
|
make type-check
|
|
```
|
|
|
|
**Tests Fail Locally**
|
|
|
|
```bash
|
|
# Ensure test dependencies are installed
|
|
uv sync --dev
|
|
|
|
# Check for leftover test data
|
|
rm -rf test_*.db
|
|
```
|
|
|
|
### Getting Help
|
|
|
|
- Check existing [GitHub Issues](https://github.com/routstr/routstr-core/issues)
|
|
- Ask in [GitHub Discussions](https://github.com/routstr/routstr-core/discussions)
|
|
- Read the [Architecture Guide](architecture.md)
|
|
|
|
## Next Steps
|
|
|
|
Now that you're set up:
|
|
|
|
1. Read the [Architecture Overview](architecture.md)
|
|
2. Check [open issues](https://github.com/routstr/routstr-core/issues)
|
|
3. Start with a small contribution
|
|
|
|
Happy coding! 🚀
|