Skip to content

development.md

Latest commit

 

History

History
162 lines (123 loc) · 4.37 KB

development.md

File metadata and controls

162 lines (123 loc) · 4.37 KB
Raw

OnRamp Development Guide

Prerequisites

  • Docker Desktop (recommended)
  • OR: Python 3.12+ and Node.js 24+ (manual setup)

Quick Start (Recommended)

./dev.sh

This single command:

  1. Builds the backend and frontend containers
  2. Starts everything with hot reload
  3. Waits for services to be healthy
  4. Prints the URLs
Service URL Hot Reload?
Frontend http://localhost:5173 ✅ Edit frontend/src/
Backend http://localhost:8000 ✅ Edit backend/app/
API Docs http://localhost:8000/docs —

Dev Script Commands

./dev.sh          # Start everything
./dev.sh down     # Stop everything
./dev.sh reset    # Wipe DB, rebuild from scratch
./dev.sh logs     # Tail all logs
./dev.sh test     # Run backend tests in container
./dev.sh status   # Show running containers + health
./dev.sh shell    # Open bash in backend container

Manual Setup (Without Docker)

Docker Compose (Full Stack)

# Start all services (SQL Server, Backend, Frontend)
docker compose up -d

# View logs
docker compose logs -f backend

# Stop everything
docker compose down

# Reset database
docker compose down -v

The Docker setup includes:

  • SQL Server 2022 Developer Edition on port 1433
  • FastAPI backend on port 8000 (with hot reload)
  • React frontend on port 5173 (with HMR)

Development Mode

When ONRAMP_AZURE_TENANT_ID is not set, the application runs in development mode:

  • Authentication returns a mock user (no Entra ID required)
  • AI calls return mock architecture responses
  • Deployment validation simulates success

Environment Variables

Variable Description Required
ONRAMP_AZURE_TENANT_ID Entra ID tenant Production
ONRAMP_AZURE_CLIENT_ID App registration client ID Production
ONRAMP_AI_FOUNDRY_ENDPOINT Azure AI Foundry endpoint Production
ONRAMP_AI_FOUNDRY_KEY AI Foundry API key Production
ONRAMP_DATABASE_URL SQL connection string Production
ONRAMP_CORS_ORIGINS Allowed CORS origins Optional

Running Tests

cd backend
source .venv/bin/activate
pytest tests/ -v

Pre-Commit Hooks

OnRamp uses pre-commit to run automated checks before each commit.

Setup

pip install pre-commit
pre-commit install

What It Checks

Hook Purpose
trailing-whitespace Removes trailing whitespace
end-of-file-fixer Ensures files end with a newline
check-yaml Validates YAML syntax
check-json Validates JSON syntax
check-merge-conflict Detects leftover merge-conflict markers
detect-private-key Prevents committing private keys
check-added-large-files Prevents committing files > 500 KB
ruff Python linting and auto-fix (backend)
ruff-format Python code formatting (backend)
eslint TypeScript/React linting (frontend)
prettier Code formatting check (frontend)

Running Manually

pre-commit run --all-files    # Run all hooks on all files
pre-commit run ruff            # Run specific hook
pre-commit autoupdate          # Update hook versions

Skipping Hooks (Emergency Only)

git commit --no-verify -m "hotfix: emergency patch"

Only skip hooks in genuine emergencies. The CI pipeline will still enforce all checks.

E2E Tests

OnRamp uses Playwright for end-to-end tests.

Running E2E Tests

cd frontend
npx playwright install chromium   # First time only
npm run test:e2e                   # Run all E2E tests
npm run test:e2e:ui                # Interactive UI mode
npm run test:e2e:headed            # Run with browser visible

E2E tests require the frontend dev server (auto-started by Playwright config).

Project Structure

onramp/
├── frontend/          # React + Fluent UI v9
├── backend/           # Python FastAPI
│   ├── app/
│   │   ├── api/routes/    # API endpoints
│   │   ├── auth/          # Entra ID auth
│   │   ├── models/        # SQLAlchemy models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   └── templates/     # Bicep templates
│   └── tests/
├── infra/             # Bicep infrastructure
└── docs/              # Documentation