Local Development Setup¶

Complete guide for setting up your local development environment for FireBreak.

Development Environment Overview¶

FireBreak uses a multi-component architecture:

Backend: Python Workers (Cloudflare)
Frontend: React + TypeScript (Vite)
Testing: pytest, Playwright
Infrastructure: Wrangler, Cloudflare CLI

Prerequisites¶

Complete these guides first:

Installation - Install all required tools
Configuration - Configure your environment

Project Structure¶

firestorm/
├── backend/              # Python backend API
│   ├── src/             # Source code
│   ├── tests/           # Backend tests
│   └── wrangler.jsonc   # Cloudflare config
├── frontend/            # Frontend applications
│   └── core/           # Main frontend app
├── qa/                  # QA testing harness
│   ├── e2e/            # End-to-end tests
│   └── harness/        # Test runner
├── tenants/             # Multi-tenant configs
├── shared/              # Shared contracts
└── docs/                # Documentation

IDE Setup¶

Visual Studio Code (Recommended)¶

Install recommended extensions:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-playwright.playwright",
    "charliermarsh.ruff"
  ]
}

Open the workspace:

code firestorm.code-workspace

PyCharm¶

Open firestorm directory as a project
Set Python interpreter to Python 3.11+
Mark backend/src as Sources Root
Enable pytest as test runner

Settings¶

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["backend/tests"],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }
}

Development Workflow¶

Terminal Setup¶

Use multiple terminal windows for parallel development:

Terminal 1: BackendTerminal 2: FrontendTerminal 3: TestsTerminal 4: Git/Commands

cd backend
npx wrangler dev --env local

Runs on: http://localhost:8787

cd frontend/core
npm run dev

Runs on: http://localhost:5173

cd qa
# Run tests as needed
npx playwright test --ui

# For git commands, running scripts, etc.
git status
git log

Hot Reload¶

Both backend and frontend support hot reload:

Backend: Wrangler auto-reloads on file changes
Frontend: Vite HMR (Hot Module Replacement)

Just save your files and see changes instantly!

Development Scripts¶

Backend Scripts¶

cd backend

# Start development server
npm run dev
# Equivalent to: npx wrangler dev --env local

# Run tests
npm test
# Equivalent to: pytest tests/

# Type check (if using mypy)
npm run type-check

# Lint code
npm run lint

Frontend Scripts¶

cd frontend/core

# Start development server
npm run dev

# Run tests
npm test

# Type check
npm run type-check

# Lint and fix
npm run lint
npm run lint:fix

# Build for production
npm run build

# Preview production build
npm run preview

Testing Workflow¶

Running Tests Locally¶

# Backend unit tests
cd backend
pytest tests/unit/ -v

# Backend integration tests
pytest tests/integration/ -v

# Frontend unit tests
cd frontend/core
npm test

# E2E tests (headless)
cd qa
npx playwright test

# E2E tests (headed - see browser)
npx playwright test --headed

# E2E tests (UI mode - interactive)
npx playwright test --ui

# E2E tests (debug mode)
npx playwright test --debug

Test-Driven Development (TDD)¶

Follow the Red-Green-Refactor cycle:

Red: Write failing test
Green: Write minimal code to pass
Refactor: Improve code quality

Example:

# Step 1: Write failing test
def test_compress_image_to_high_quality():
    """Test image compression to 500KB target"""
    result = compress_image(large_image, target_kb=500)
    assert 400 <= get_size_kb(result) <= 600

# Step 2: Run test (should fail)
pytest tests/test_compression.py -v

# Step 3: Implement feature
def compress_image(image, target_kb):
    # ... implementation
    return compressed_image

# Step 4: Run test (should pass)
pytest tests/test_compression.py -v

# Step 5: Refactor
# Improve code quality while keeping tests passing

See TDD Workflow for details.

Git Workflow¶

Branch Naming¶

# Feature branch
git checkout -b feature/photo-upload-enhancement

# Bug fix
git checkout -b fix/cors-header-issue

# Sprint work
git checkout -b sprint2/multi-tenant-setup

# Hotfix
git checkout -b hotfix/critical-security-patch

Commit Messages¶

Follow conventional commits:

# Format: <type>(<scope>): <description>

git commit -m "feat(backend): Add photo compression endpoint"
git commit -m "fix(frontend): Resolve CORS preflight issue"
git commit -m "docs(api): Update authentication guide"
git commit -m "test(qa): Add E2E tests for upload flow"
git commit -m "refactor(backend): Extract validation logic"

Types: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - perf: Performance improvement - chore: Maintenance

Pull Request Process¶

Create feature branch
Make changes and commit
Run tests locally
Push to GitHub
Create Pull Request
Wait for CI/CD checks
Request review
Address feedback
Merge after approval

Debugging¶

Backend Debugging¶

Using Print Statements¶

# In backend code
print(f"Request path: {request.url}")
print(f"Request method: {request.method}")
print(f"Request body: {await request.text()}")

View output in Wrangler terminal.

Using Wrangler Tail¶

# Tail logs in real-time
wrangler tail --env local

# Filter for errors
wrangler tail --env local --status error

Using Python Debugger¶

# Add breakpoint
import pdb; pdb.set_trace()

# Or use built-in breakpoint()
breakpoint()

Frontend Debugging¶

Browser DevTools¶

Open Chrome/Firefox DevTools (F12)
Go to Sources tab
Set breakpoints
Reload page

Console Logging¶

console.log('API response:', response);
console.error('Error occurred:', error);
console.debug('Debug info:', debugInfo);

React DevTools¶

Install React Developer Tools extension.

Test Debugging¶

Playwright Debugging¶

# Debug mode (step through)
npx playwright test --debug

# UI mode (interactive)
npx playwright test --ui

# Show browser
npx playwright test --headed

# Specific test
npx playwright test tests/photo-upload.spec.ts --debug

pytest Debugging¶

# Show print statements
pytest tests/test_api.py -s

# Stop on first failure
pytest tests/test_api.py -x

# Show detailed output
pytest tests/test_api.py -vv

# Run specific test
pytest tests/test_api.py::test_health_endpoint -v

Performance Monitoring¶

Local Performance Testing¶

# Backend response time
cd backend
time curl http://localhost:8787/api/v1/health

# Frontend build time
cd frontend/core
time npm run build

# Load testing with k6
cd qa/performance
k6 run scenarios/photo_upload_load.js

Profiling¶

Python Profiling¶

import cProfile
import pstats

def profile_function():
    profiler = cProfile.Profile()
    profiler.enable()

    # Your code here
    result = expensive_function()

    profiler.disable()
    stats = pstats.Stats(profiler)
    stats.sort_stats('cumtime')
    stats.print_stats(10)  # Top 10 slowest

Code Quality Tools¶

Linting¶

# Backend (Python)
cd backend
ruff check src/
black src/ --check

# Frontend (TypeScript)
cd frontend/core
npm run lint

Type Checking¶

# Backend (mypy)
cd backend
mypy src/

# Frontend (TypeScript)
cd frontend/core
npm run type-check

Pre-commit Hooks¶

Set up pre-commit hooks to run checks automatically:

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Now checks run automatically on git commit

Environment Variables¶

Create .env files for local development:

Backend `.env`¶

cd backend
cat > .env << EOF
ENVIRONMENT=local
API_VERSION=v1
DEBUG=true

# Optional: API keys for testing
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
EOF

Frontend `.env`¶

cd frontend/core
cat > .env << EOF
VITE_API_BASE_URL=http://localhost:8787/api/v1
VITE_ENABLE_DEBUG=true
VITE_TENANT_ID=default
EOF

Don't Commit .env Files

Add .env to .gitignore to prevent accidental commits of secrets.

Tips & Best Practices¶

1. Use Virtual Environments¶

# Create virtual environment
python -m venv venv

# Activate
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

2. Keep Dependencies Updated¶

# Backend
pip list --outdated
pip install --upgrade package-name

# Frontend
npm outdated
npm update

3. Clear Cache When Needed¶

# Backend
rm -rf __pycache__
rm -rf .pytest_cache

# Frontend
rm -rf node_modules
rm -rf dist
npm install

4. Use npm Scripts¶

Add custom scripts to package.json:

{
  "scripts": {
    "dev": "wrangler dev --env local",
    "test": "pytest tests/",
    "test:watch": "pytest-watch",
    "lint": "ruff check src/",
    "format": "black src/"
  }
}

Next Steps¶

Coding Standards - Code style guide
Git Workflow - Detailed Git workflows
Team Coordination - Working with teams
Contributing - Contribution guidelines