Bill of Materials (BOM) Guide

The BOM system helps estimate construction and setup costs for production modules at property sites.

Overview

The Bill of Materials system bridges the gap between abstract production modules (orchards, poultry systems, greenhouses) and concrete financial planning. It provides:

• Material catalogs with default costs and supplier information
• Module BOMs defining what materials are needed for each production module
• Property BOMs that apply module BOMs to specific properties with area scaling
• Budget integration to generate budget line items from BOM costs

Key Concepts

Material Categories

Materials are organized into 9 categories:

Production Modules

The system includes 8 pre-defined production modules:

1. Module 1: Orchard - Fruit trees with integrated poultry and bees
2. Module 2: Berry Fruits - Traditional hedgerow berry production
3. Module 3: Pasture - Grazing with fodder crops
4. Module 4: Annual Vegetables - Seasonal vegetable production
5. Module 5: Perennial Vegetables - Low-maintenance food forest understory
6. Module 6: Protected Cropping - Greenhouses and polytunnels
7. Module 7: Aquaculture - Fish and aquatic systems
8. Module 8: Processing/Storage - Post-harvest handling

Installation Years

BOM items can be assigned to installation years 0-5:

• Year 0: Initial setup costs (infrastructure, permanent structures)
• Years 1-5: Phased additions (livestock, equipment upgrades)

This enables realistic cash flow planning across the project timeline.

Using the BOM System

Via Admin Interface

1. Navigate to Admin > BOM section
2. Materials: Browse and manage the material catalog
3. Production Module BOMs: View/edit module definitions
4. Property BOMs: Create property-specific cost estimates

Via API

The BOM API is available at /api/bom/:

# List all materials
GET /api/bom/materials/

# Get materials by category
GET /api/bom/materials/by_category_type/?type=FENCING

# Calculate module BOM cost (scaled to 2 hectares)
GET /api/bom/production-module-boms/1/calculate/?area=2.0

# Calculate property BOM and cache results
POST /api/bom/property-boms/1/calculate/

# Preview budget lines before generating
GET /api/bom/property-boms/1/preview_budget_lines/

# Generate budget lines from BOM
POST /api/bom/property-boms/1/generate_budget_lines/

Cost Calculations

The system automatically handles:

• Area scaling: Costs scale proportionally when a property's allocated area differs from the module's reference area
• Scenario overrides: FinancialScenario-specific pricing (bulk discounts, regional suppliers)
• Year-by-year breakdown: Costs grouped by installation year for cash flow planning

Integration with Other Systems

Budget Categories

Each MaterialCategory links to a BudgetCategory from the finance app:

• FENCING, IRRIGATION, STRUCTURES, INFRASTRUCTURE → INFRASTRUCTURE budget
• PLANTS → FOOD budget
• EQUIPMENT → EQUIPMENT budget
• LIVESTOCK → LIVESTOCK budget

ShowcaseBudgetLine Generation

The generate_budget_lines action creates ShowcaseBudgetLine entries:

1. Groups costs by budget category and year
2. Creates budget lines for year_0 through year_5
3. Links to the PropertyShowcase's OperationalPlan

FinancialScenario Overrides

For properties with multiple financial scenarios (e.g., different loan structures), you can:

1. Create BOMMaterialOverride entries for specific materials
2. Override unit costs or quantities per scenario
3. Compare total costs across scenarios

Seed Data

The system includes seed data loaded via:

python manage.py seed_bom_materials

This creates: - 20 material categories - 51 materials with default costs

Categories and materials are based on the INFRASTRUCTURE data in data/food_production_data.py.

Rate Limiting

Expensive BOM operations are rate-limited to prevent abuse:

• calculate action: 20 requests/hour
• generate_budget_lines action: 20 requests/hour

If you hit the rate limit, wait before retrying.