reference-code.md

Reference Code Guide

Important: Reference code is NOT manually edited application code. It's a translation source for the LLM. The Compose workflow is:

1. Write business logic in reference/ (Python, SQL, etc.)
2. Reference it in .compose files
3. LLM generates target code (TypeScript, Rust, etc.)
4. Users never manually edit the generated code
5. All changes go through .compose files or reference/ updates

What is the reference/ Directory?

The reference/ directory contains implementation code in any language that serves as a blueprint for the LLM. The LLM reads this code and translates it to your target language, preserving the exact business logic.

When to Use Reference Code

Use reference code when you have:

• Complex business logic that's hard to describe in English
• Mathematical algorithms that need precision
• Existing code you want to preserve across platforms
• Database queries with specific optimization patterns
• Validation rules with many edge cases

How It Works

1. Write Reference Implementation

In reference/, create files with your business logic in any language:

# reference/pricing.py

def calculate_loyalty_discount(amount, years_member):
    """
    Calculate loyalty discount based on membership duration.
    Business rules approved by CEO on 2024-01-15.
    """
    if years_member >= 5:
        return amount * 0.15  # 15% for 5+ years
    elif years_member >= 3:
        return amount * 0.10  # 10% for 3-4 years
    elif years_member >= 1:
        return amount * 0.05  # 5% for 1-2 years
    else:
        return 0  # No discount for new members

2. Reference in .compose File

Use @reference/filename in your guides:

guide "Loyalty Discount Calculation":
  - Reference: @reference/pricing.py::calculate_loyalty_discount
  - Translate this function to target language
  - Preserve exact percentage thresholds
  - Round to 2 decimal places

3. LLM Translates to Target

For TypeScript:

function calculateLoyaltyDiscount(amount: number, yearsMember: number): number {
  if (yearsMember >= 5) {
    return amount * 0.15;
  } else if (yearsMember >= 3) {
    return amount * 0.10;
  } else if (yearsMember >= 1) {
    return amount * 0.05;
  } else {
    return 0;
  }
}

For Rust:

fn calculate_loyalty_discount(amount: f64, years_member: u32) -> f64 {
    if years_member >= 5 {
        amount * 0.15
    } else if years_member >= 3 {
        amount * 0.10
    } else if years_member >= 1 {
        amount * 0.05
    } else {
        0.0
    }
}

Best Practices

Use Python for Business Logic

# Easy to read, validate, and share with non-technical stakeholders
def calculate_tax(amount, region):
    tax_rates = {
        'CA': 0.0725,
        'NY': 0.08875,
        'TX': 0.0625
    }
    return amount * tax_rates.get(region, 0.05)

Use SQL for Complex Queries

-- reference/reports.sql
-- Monthly revenue report with customer segmentation
SELECT 
  DATE_TRUNC('month', order_date) as month,
  customer_tier,
  COUNT(DISTINCT customer_id) as unique_customers,
  SUM(total) as revenue
FROM orders
WHERE order_date >= CURRENT_DATE - INTERVAL '12 months'
GROUP BY month, customer_tier
ORDER BY month DESC, revenue DESC;

Use JavaScript for Algorithms

// reference/validation.js
// Email validation with specific corp rules
function isValidCorporateEmail(email) {
  // Must be company domain
  const validDomains = ['company.com', 'subsidiary.com'];
  const domain = email.split('@')[1];
  
  if (!validDomains.includes(domain)) {
    return false;
  }
  
  // No plus addressing allowed
  if (email.includes('+')) {
    return false;
  }
  
  return /^[a-z0-9.]+@[a-z0-9]+\.[a-z]+$/.test(email);
}

Ownership

Reference code can be owned by different teams:

reference/
├── pricing/          # Product team owns
│   ├── discounts.py
│   └── promotions.py
├── validation/       # Security team owns
│   └── rules.js
├── analytics/        # Data team owns
│   └── queries.sql
└── integrations/     # Engineering team owns
    └── third_party.py

Version Control

Reference code is version controlled like any code:

git log reference/pricing.py

commit abc123
Author: Product Manager <pm@company.com>
Date: 2024-01-15

  Update loyalty thresholds per CEO approval
  - 5+ years: 10% → 15%
  - 3-4 years: 8% → 10%

Framework-Agnostic

The same reference code works for all targets:

# Same pricing.py referenced
compose build --target react      # → TypeScript
compose build --target vue        # → JavaScript  
compose build --target flutter    # → Dart
compose build --target ios        # → Swift

Testing Reference Code

Test your reference implementations independently:

# reference/pricing.py
def calculate_discount(amount, tier):
    # implementation...

# tests/test_pricing.py
def test_gold_tier_discount():
    assert calculate_discount(100, 'gold') == 15
    
def test_silver_tier_discount():
    assert calculate_discount(100, 'silver') == 10

Once tests pass, you know the logic is correct for ALL target platforms.

Examples

See complete examples in:

• examples/ecommerce-with-reference/ - Shows @ operator usage
• examples/payment-system-evolution.md - Shows how guides grow over time

Summary

Reference code is NOT imported - it's a translation source. Write once in Python → Generate for any language Business logic stays consistent across all platforms.