Skip to content

Local Development

⏱️ Time: 10 minutes | 🎯 Goal: Run the system locally for fast development

The fastest way to get Loan Defenders running. Perfect for daily development, debugging, and rapid iteration with hot-reload.

Prerequisites

Verify before starting:

# Check Python
python --version  # Need 3.11+

# Check Node.js
node --version  # Need 18+

# Check uv
uv --version  # Install: curl -LsSf https://astral.sh/uv/install.sh | sh

# Check Azure CLI
az --version  # Install: https://learn.microsoft.com/cli/azure/install-azure-cli

# Login to Azure
az login

Required: - Python 3.11+ - Node.js 18+ - uv package manager - Azure CLI - Azure AI Foundry account with GPT-4+ access

Windows users: Use WSL2 or Git Bash.

Quick Start

1. Clone and Configure

# Clone repository
git clone https://github.com/niksacdev/loan-defenders.git
cd loan-defenders

# Create environment file
cp .env.example .env

# Edit .env - add your Azure credentials:
# AZURE_AI_PROJECT_ENDPOINT=https://your-resource.services.ai.azure.com/api/projects/your-project
# AZURE_AI_MODEL_DEPLOYMENT_NAME=your-deployment-name

Get credentials from Azure AI Foundry → Your Project → Overview

2. Install Dependencies

# Install UI dependencies (must be first)
cd apps/ui && npm install && cd ../..

# Install Python packages
uv sync

3. Start Services

# Start all 5 services (API, UI, 3 MCP servers)
./scripts/start_local_dev.sh

What it does: - Validates prerequisites - Checks ports (8000, 8010-8012, 5173) - Starts all services in background - Creates logs in logs/ directory - Waits for health checks

Output: 

========================================
  All services started successfully!
========================================

Service URLs:
  • API:                          http://localhost:8000
  • UI:                           http://localhost:5173
  • MCP Application Verification: http://localhost:8010
  • MCP Document Processing:      http://localhost:8011
  • MCP Financial Calculations:   http://localhost:8012

🎉 Ready! Open http://localhost:5173

4. Verify It Works

# Open in browser
open http://localhost:5173  # macOS
# or manually navigate to http://localhost:5173

# Check service status
./scripts/status_local_dev.sh

# View logs
tail -f logs/*.log  # All logs
tail -f logs/api.log  # API only

Test it: 1. Click "Start Your Loan Application" 2. Fill in test data 3. Submit and watch agents process 4. Verify loan decision appears (30-60 seconds)

Managing Services

# Check status
./scripts/status_local_dev.sh

# View logs
tail -f logs/api.log
tail -f logs/ui.log
tail -f logs/mcp-*.log

# Stop all services
./scripts/stop_local_dev.sh

Development Workflow

Hot Reload

Frontend (React/Vite): - Edit files in apps/ui/src/ - Changes reload automatically - No restart needed

Backend (FastAPI): - Edit files in apps/api/loan_defenders/ - API reloads automatically (uvicorn --reload) - No manual restart needed

MCP Servers: - Edit files in apps/mcp_servers/*/ - Requires restart: Stop and restart specific server

Running Tests

# All tests
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ --cov=apps/api --cov-report=html

# Specific module
uv run pytest tests/unit/agents/ -v

Code Quality

# Lint and format
uv run ruff check . --fix
uv run ruff format .

Troubleshooting

Port Already in Use

Error: Address already in use

# Find process using port
lsof -i :8000  # or :8010, :8011, :8012, :5173

# Kill process
kill -9 <PID>

# Or stop all services first
./scripts/stop_local_dev.sh

Connection Errors

Error: "I'm sorry, I'm having trouble connecting right now"

Common causes:

  1. API not running 

    # Check API status
curl http://localhost:8000/health

# If fails, check logs
tail -f logs/api.log

  2. CORS configuration 

    # Verify .env has correct CORS origins
grep CORS .env

# Should include: http://localhost:5173
APP_CORS_ORIGINS="http://localhost:5173,http://localhost:5174"

  3. MCP servers not responding 

    # Test MCP endpoints
curl http://localhost:8010/health
curl http://localhost:8011/health
curl http://localhost:8012/health

# If fails, restart services
./scripts/stop_local_dev.sh
./scripts/start_local_dev.sh

Module Not Found

Error: ModuleNotFoundError: No module named 'loan_defenders_models'

# Reinstall dependencies
uv sync

# Verify installation
uv run python -c "from loan_defenders_models import LoanApplication; print('OK')"

Azure Authentication Failed

Error: Azure authentication failed

# Re-authenticate
az login

# Verify account
az account show

# Check subscription
az account list

Special Environments

GitHub Codespaces

If using GitHub Codespaces, additional configuration needed:

See: Codespaces Setup Guide

Key differences: - Port 8000 (API) must be public - UI needs apps/ui/.env with Codespaces URL - CORS must include Codespaces domain

What's Next?

Continue Development: - System Architecture - Understand how it works - Agent Framework - Multi-agent patterns - MCP Servers - Tool server design

Test with Docker: - Docker Development - Containerized testing

Deploy to Azure: - Azure Deployment - Production deployment

Need Help? - Troubleshooting Guide - Common issues - GitHub Discussions - Ask questions

🎉 You're running Loan Defenders locally! Start coding with hot-reload.

Common Issues & Solutions

Port Already in Use

If ports are already in use: 

# Automatically kill processes on required ports
./scripts/start_local_dev.sh --force

# Or manually check and kill
lsof -i :8000
kill $(lsof -t -i:8000)

UI Shows "vite: not found"

The script now automatically installs vite, but if you encounter this: 

cd apps/ui
rm -rf node_modules package-lock.json
npm install --include=dev

API Can't Connect to MCP Servers

Check that .env.local has correct localhost URLs: 

cat .env.local | grep MCP_
# Should show: MCP_*_URL=http://localhost:*

If wrong, delete and regenerate: 

rm .env.local
./scripts/start_local_dev.sh

Azure AI Permission Errors

Error: "lacks the required data action agents/write"

Solution: Assign Azure AI Developer role: 1. Go to Azure Portal → Your Resource Group 2. Access Control (IAM) → Add role assignment 3. Role: Azure AI Developer 4. Assign to your user account 5. Restart services

Model Version Empty Error

Error: "response_format not supported with model version ''"

Solution: Check model deployment name: 1. Go to Azure AI Foundry portal 2. Navigate to your project → Deployments 3. Verify deployment name matches .env 4. Ensure model supports json_schema (GPT-4o 2024-08-06+)

Service Management

Check Status

./scripts/status_local_dev.sh

Shows health status for all 5 services with PIDs and ports.

Stop Services

./scripts/stop_local_dev.sh

Gracefully stops all services and cleans up ports.

View Logs

# All logs
tail -f logs/*.log

# Specific service
tail -f logs/api.log
tail -f logs/ui.log
tail -f logs/mcp-app-verification.log

Restart Services

./scripts/stop_local_dev.sh && ./scripts/start_local_dev.sh

What's Different from Docker/Azure?

Local Development

  • ✅ Fast iteration (no container rebuilds)
  • ✅ Hot reload for code changes
  • ✅ Direct debugging with breakpoints
  • ✅ localhost URLs everywhere
  • ✅ Each service runs as separate process

Docker Development (Stage 2)

  • Container networking (internal DNS)
  • Production-like environment
  • Isolated dependencies

Azure Deployment (Stage 3)

  • Managed identity authentication
  • Application Gateway for routing
  • Container Apps for auto-scaling

Development Workflow

  1. Make code changes to any service
  2. Services auto-reload (API, MCP servers, UI)
  3. Test in browser at http://localhost:5173
  4. Check logs if something breaks
  5. Commit changes when working

The startup script ensures a consistent environment every time, so you can focus on coding!

Next Steps