Development¶

Development guides, workflows, and best practices for contributing to FireBreak.

Getting Started¶

New to FireBreak development? Start here:

Local Setup

Set up your development environment

Complete guide for IDE, tools, and workflow
Coding Standards

Code style and quality guidelines

Python, TypeScript, and general best practices
Git Workflow

Branching, commits, and pull requests

How we use Git and GitHub
Team Coordination

Multi-team development workflow

Sprint planning and collaboration

Development Workflow¶

1. Setup Your Environment¶

# Clone repository
git clone https://github.com/firebreakrisk/firestorm.git
cd firestorm

# Install dependencies
cd backend && npm install && pip install -r requirements.txt
cd ../frontend/core && npm install
cd ../qa && pip install -r requirements.txt

See Local Setup for complete instructions.

2. Create Feature Branch¶

# Create branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

See Git Workflow for branching strategy.

3. Write Tests First (TDD)¶

# Write failing test
def test_new_feature():
    result = new_feature()
    assert result == expected

# Run test (should fail)
pytest tests/test_new_feature.py

# Implement feature
def new_feature():
    return expected

# Run test (should pass)
pytest tests/test_new_feature.py

See TDD Workflow.

4. Implement Feature¶

Follow Coding Standards:

Use type hints in Python
Follow naming conventions
Add docstrings
Keep functions small and focused

5. Run Tests Locally¶

# Backend tests
cd backend
pytest tests/ -v

# Frontend tests
cd frontend/core
npm test

# E2E tests
cd qa
npx playwright test

6. Commit Changes¶

# Stage changes
git add .

# Commit with conventional format
git commit -m "feat(backend): Add photo compression endpoint"

# Push to GitHub
git push origin feature/your-feature-name

See Git Workflow for commit message format.

7. Create Pull Request¶

Go to GitHub repository
Click "New Pull Request"
Select your feature branch
Fill out PR template
Request review from team members
Wait for CI/CD checks to pass
Address review feedback
Merge after approval

Team Structure¶

FireBreak is developed by specialized teams:

Team	Focus Area	Working Directory
Team Alpha	Backend & API	`backend/`
Team Beta	Frontend	`frontend/`
Team Gamma	Multi-Tenant	`tenants/`, `infrastructure/`
Team Delta	QA & Testing	`qa/`
Team Epsilon	DevOps & CI/CD	`.github/`

See Team Coordination for collaboration details.

Development Tools¶

Required Tools¶

Node.js 20+
Python 3.11+
Git
Wrangler CLI (for Cloudflare Workers)

Recommended IDEs¶

Visual Studio Code (with recommended extensions)
PyCharm (Professional or Community)
WebStorm (for frontend focus)

Code Quality Tools¶

Python: ruff, black, mypy
TypeScript: eslint, prettier
Testing: pytest, Playwright
Pre-commit hooks: automated checks before commit

See Local Setup for installation.

Coding Standards¶

Python¶

from typing import Optional

async def get_assessment(
    assessment_id: str,
    tenant_id: str,
    env
) -> Optional[dict]:
    """
    Fetch assessment with tenant validation.

    Args:
        assessment_id: Unique assessment identifier
        tenant_id: Tenant identifier for isolation
        env: Worker environment

    Returns:
        Assessment dict or None if not found

    Raises:
        ForbiddenError: If tenant validation fails
    """
    # Implementation
    pass

TypeScript¶

/**
 * Upload photo to backend API
 *
 * @param photo - Photo file to upload
 * @param tenantId - Tenant identifier
 * @returns Upload result with photo ID
 * @throws ApiError if upload fails
 */
async function uploadPhoto(
  photo: File,
  tenantId: string
): Promise<UploadResult> {
  // Implementation
}

See Coding Standards for complete guide.

Testing Best Practices¶

Write Tests First¶

# ❌ Don't write code first
def compress_image(image):
    # ... implementation
    pass

def test_compress_image():
    # ... test after
    pass

# ✅ Write test first
def test_compress_image():
    """Test image compression to target size"""
    result = compress_image(large_image, target_kb=500)
    assert 400 <= get_size_kb(result) <= 600

def compress_image(image, target_kb):
    # Now implement to pass test
    pass

Test One Thing¶

# ❌ Testing multiple things
def test_everything():
    result = upload_and_analyze(photo)
    assert result.uploaded
    assert result.analyzed
    assert result.report_generated

# ✅ Test one thing per test
def test_upload_photo():
    result = upload_photo(photo)
    assert result.uploaded

def test_analyze_photo():
    result = analyze_photo(photo)
    assert result.analyzed

def test_generate_report():
    result = generate_report(analysis)
    assert result.report_generated

See TDD Workflow.

Documentation¶

Code Documentation¶

Docstrings: All public functions and classes
Type Hints: All function signatures
Comments: Complex logic only (prefer self-documenting code)

User Documentation¶

API Documentation: OpenAPI spec + examples
Deployment Guides: Step-by-step instructions
Architecture Docs: ADRs for major decisions

Contributing to Docs¶

Documentation is in docs/ directory:

# Edit documentation
code docs/

# Preview with MkDocs
mkdocs serve

# Build static site
mkdocs build

See Contributing.

Common Tasks¶

Adding a New API Endpoint¶

Write API contract in shared/api-contract.json
Write tests in backend/tests/test_api.py
Implement handler in backend/src/handlers/
Add route in backend/src/index.py
Update API documentation
Test locally and create PR

Adding a New Frontend Component¶

Write component tests in frontend/core/tests/
Implement component in frontend/core/src/components/
Add to Storybook (if applicable)
Test in isolation and integration
Document props and usage
Create PR with screenshots

Setting Up New Tenant¶

Run provisioning script: ./scripts/provision-tenant.sh tenant-id
Configure branding in tenants/tenant-id/config.json
Deploy branded frontend
Test end-to-end workflow
Document tenant-specific setup

See specific guides for detailed steps.

Troubleshooting¶

Tests Failing Locally¶

# Clear cache
rm -rf __pycache__ .pytest_cache

# Reinstall dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run single test for debugging
pytest tests/test_specific.py::test_function -vv

Build Errors¶

# Backend
cd backend
rm -rf node_modules
npm install

# Frontend
cd frontend/core
rm -rf node_modules dist
npm install
npm run build

Environment Issues¶

# Check Python version
python --version  # Should be 3.11+

# Check Node version
node --version  # Should be 20+

# Verify Wrangler
npx wrangler --version