Contributing¶

Development environment setup, CI pipeline, and contribution workflow.

Development Setup¶

Prerequisites¶

Python 3.13+
Node.js 22+
PostgreSQL 16+
Redis 7+
uv (Python package manager)

Backend¶

cd backend
uv sync --extra dev           # Install dependencies + dev tools
cp .env.example .env          # Configure environment
uv run python manage.py migrateschema -as   # Migrate all schemas
uv run python manage.py runserver           # Dev server at http://localhost:8000

Frontend¶

# Admin dashboard
cd frontend/admin
npm install
npm run dev                   # Vite dev server at http://localhost:5173

# Borrower portal
cd frontend/borrower
npm install
npm run dev                   # Vite dev server at http://localhost:5174

Docker Alternative¶

docker compose up -d          # Start all services

See Docker for details.

CI Pipeline¶

GitHub Actions runs on every push and pull request. The pipeline has four parallel jobs:

Backend Job (20-min timeout)¶

Services: PostgreSQL 16, Redis 7

Step	Command	Purpose
Lint	`uv run ruff check .`	Code style and error detection
Format	`uv run ruff format --check .`	Formatting verification
Type check	`uv run mypy .`	Static type analysis (strict mode)
Tests	`uv run pytest`	Full test suite (1200+ tests)

Frontend Admin Job (10-min timeout)¶

Step	Command	Purpose
Lint	`npm run lint`	ESLint
Type check	`npx tsc --noEmit`	TypeScript compilation
Tests	`npm run test`	Vitest (360+ tests)

Borrower Portal Job (10-min timeout)¶

Same steps as admin frontend.

Documentation Job (5-min timeout)¶

Step	Command	Purpose
Build	`uv run mkdocs build --strict`	Verify docs build with no warnings

Concurrency¶

The pipeline cancels previous runs on the same branch to save resources.

Code Quality Commands¶

cd backend

# Lint (auto-fix)
uv run ruff check --fix .

# Format
uv run ruff format .

# Type check
uv run mypy .

# Run all tests
uv run pytest

# Run specific app tests
uv run pytest apps/loans/tests/

# Run with verbose output
uv run pytest -v --tb=long

Always use uv run

Dev tools (pytest, ruff, mypy) are installed in the uv-managed virtualenv. Never run them bare — use uv run pytest, not pytest.

Code Review Checklist¶

[ ] Tests written and passing for new functionality
[ ] Code follows existing project conventions
[ ] No ruff lint warnings (uv run ruff check .)
[ ] No mypy type errors (uv run mypy .)
[ ] Commit messages explain "why" not just "what"
[ ] No secrets or credentials in committed files
[ ] Migration files included for model changes
[ ] API endpoints documented with operation_id, summary, and field descriptions