> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 6.1: Model Design Best Practices

> Apply the four principles of effective model design: least complexity, explicit over implicit, audit trail everything, and don't repeat yourself.

<Panel>
  <Card title="Accounting Academy" className="accounting-academy-card">
    <div className="accounting-academy-content">
      <Steps className="my-0">
        <Step title="MODULE 1: Fundamentals" icon="bookmark" iconType="solid" stepNumber={1} titleSize="p">
          * [1.1: Core Concepts & the Data Lifecycle](/accounting-academy/module-1/1-1-core-concepts-data-lifecycle)
          * [1.2: Translating Methodologies to Mangrove](/accounting-academy/module-1/1-2-translating-methodologies-to-mangrove)
          * [1.3: Events and Datapoints](/accounting-academy/module-1/1-3-events-and-datapoints)
          * [Exercise: Design and Build](/accounting-academy/module-1/1-exercise-design-and-build)
        </Step>

        <Step title="MODULE 2: Calculations" icon="bookmark" iconType="solid" stepNumber={2} titleSize="p">
          * [2.1: Calculation Architecture](/accounting-academy/module-2/2-1-calculation-architecture)
          * [2.2: Expanding Your Data Model](/accounting-academy/module-2/2-2-expanding-your-data-model)
          * [Exercise: Multi-Step Calculations](/accounting-academy/module-2/2-exercise-multi-step-calculations)
        </Step>

        <Step title="MODULE 3: Batch Partitioning & LCA" icon="bookmark" iconType="solid" stepNumber={3} titleSize="p">
          * [3.1: What Is a Batch?](/accounting-academy/module-3/3-1-what-is-a-batch)
          * [3.2: Batch Partitioning Strategies](/accounting-academy/module-3/3-2-batch-partitioning)
          * [3.3: Life Cycle Assessment & Emissions](/accounting-academy/module-3/3-3-lca-and-emissions)
          * [3.4: Allocating Emissions to Batches](/accounting-academy/module-3/3-4-allocating-emissions-to-batches)
          * [Exercise: Batch Partitioning & LCA](/accounting-academy/module-3/3-exercise-batch-partitioning-and-lca)
        </Step>

        <Step title="MODULE 4: Mass Balance with Ledgers" icon="bookmark" iconType="solid" stepNumber={4} titleSize="p">
          * [4.1: Introduction to Mass Balance](/accounting-academy/module-4/4-1-intro-to-mass-balance)
          * [4.2: Designing the Ledger Structure](/accounting-academy/module-4/4-2-designing-the-ledger-structure)
          * [4.3: Multiple Batch Types for Different Stages](/accounting-academy/module-4/4-3-multiple-batch-types)
          * [Exercise: Design & Build Mass Balance](/accounting-academy/module-4/4-exercise-design-and-build-mass-balance)
        </Step>

        <Step title="MODULE 5: Integration Testing" icon="bookmark" iconType="solid" stepNumber={5} titleSize="p">
          * [5.1: The Complete Model Assembly](/accounting-academy/module-5/5-1-the-complete-model-assembly)
          * [5.2: Testing Patterns](/accounting-academy/module-5/5-2-testing-patterns)
          * [5.3: Common Integration Pitfalls](/accounting-academy/module-5/5-3-common-integration-pitfalls)
          * [Exercise: Integration Testing](/accounting-academy/module-5/5-exercise-integration-testing)
        </Step>

        <Step title="MODULE 6: Advanced Patterns & Production" icon="bookmark" iconType="solid" stepNumber={6} titleSize="p">
          * [6.1: Model Design Best Practices](/accounting-academy/module-6/6-1-model-design-best-practices)
          * [6.2: Advanced Techniques](/accounting-academy/module-6/6-2-advanced-techniques)
          * [6.3: Production Readiness](/accounting-academy/module-6/6-3-production-readiness)
          * [Exercise: Production Deployment](/accounting-academy/module-6/6-exercise-production-deployment)
        </Step>
      </Steps>
    </div>
  </Card>
</Panel>

<Check>
  **What you'll learn in this lesson:**

  * Apply the Principle of Least Complexity to keep models maintainable
  * Make calculations explicit and self-documenting
  * Ensure every output is traceable back to source data
  * Reuse components to reduce duplication and errors
</Check>

You've built a working project through Modules 1-5. Now it's time to make it **production-ready** — not just functional, but maintainable, auditable, and clear to anyone who inherits it. This lesson introduces four design principles that separate good models from great ones.

## The four principles

<CardGroup cols={2}>
  <Card icon="minimize" title="1. Least Complexity">
    **Keep models as simple as the methodology allows.**

    Don't add calculation steps that the methodology doesn't require. Don't optimize prematurely. A simple model that's correct is worth more than a clever model that's hard to verify.
  </Card>

  <Card icon="eye" title="2. Explicit Over Implicit">
    **Clear, documented logic beats clever shortcuts.**

    Every unit conversion, every factor application, every conditional branch should be a visible node in the model — not hidden inside a complex Keisan expression.
  </Card>

  <Card icon="link" title="3. Audit Trail Everything">
    **Traceability from credit to source event.**

    Every output value should be traceable backwards through the model tree to the specific events and evidence that produced it. Verifiers will follow this trail.
  </Card>

  <Card icon="copy" title="4. Don't Repeat Yourself">
    **Reusable components and calculations.**

    If two batch types use the same emission factor calculation, build it once and reference it. Duplication creates drift — when one copy is updated, the other becomes wrong.
  </Card>
</CardGroup>

## Principle 1: Least Complexity

```mermaid theme={null}
flowchart LR
    subgraph Bad["Over-Engineered"]
        B1["Step 1"] --> B2["Step 2"]
        B2 --> B3["Step 3"]
        B3 --> B4["Step 4"]
        B4 --> B5["Step 5"]
        B5 --> B6["Step 6"]
        B6 --> B7["Output"]
    end

    subgraph Good["Methodology-Aligned"]
        G1["Input"] --> G2["Calculate"]
        G2 --> G3["Output"]
    end

    style B1 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B2 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B3 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B4 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B5 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B6 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style B7 fill:#ef5350,stroke:#c62828,stroke-width:1px,color:#000
    style G1 fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style G2 fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style G3 fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
```

**In practice:**

* Map each model step to a specific equation in the methodology document
* If a calculation step doesn't correspond to a methodology requirement, question whether it's needed
* Avoid "future-proofing" — add complexity only when the methodology demands it
* Prefer fewer, well-understood nodes over many granular sub-calculations

<Note>
  Least complexity doesn't mean least steps. Breaking a formula into intermediate nodes (as you did in Module 2) is good design — it adds **clarity** without adding unnecessary **logic**. The principle is about not adding logic the methodology doesn't require.
</Note>

## Principle 2: Explicit Over Implicit

Every transformation should be **visible** in the model:

<Tabs>
  <Tab title="Implicit (avoid)">
    A single Keisan expression that does everything:

    ```
    result = (wet_mass * (1 - moisture/100) * carbon_pct/100 * 3.67) -
             (kwh * 0.000417 + gallons * 0.00572) *
             (biochar_mass / total_mass)
    ```

    This is hard to audit, hard to debug, and impossible to verify intermediate values.
  </Tab>

  <Tab title="Explicit (prefer)">
    Separate nodes for each step:

    1. `dry_mass = wet_mass × (1 - moisture/100)`
    2. `carbon_mass = dry_mass × carbon_pct/100`
    3. `gross_co2e = carbon_mass × 3.67`
    4. `elec_emissions = kwh × grid_factor / 1000`
    5. `prop_emissions = gallons × prop_factor / 1000`
    6. `allocated_emissions = (elec + prop) × mass_proportion`
    7. `net_co2e = gross_co2e - allocated_emissions`

    Each step is verifiable. Intermediate values are visible in the Console.
  </Tab>
</Tabs>

<Tip>
  Name every intermediate node descriptively. A node called `dry_feedstock_mass_tonnes` tells a verifier exactly what it is. A node called `calc_step_2` tells them nothing.
</Tip>

## Principle 3: Audit Trail Everything

Verifiers trace the chain: **credit → report → batch → model calculation → event → evidence**. Every link in this chain must be unbroken.

<Steps>
  <Step title="Output → Calculation">
    Every batch output datapoint should trace to a specific model output node.
  </Step>

  <Step title="Calculation → Input">
    Every model node should trace to specific datapoint slugs from event types or static inputs.
  </Step>

  <Step title="Input → Event">
    Every datapoint value should trace to a specific event instance with a date, source, and tracking ID.
  </Step>

  <Step title="Event → Evidence">
    Every event should have associated <a href="/production-accounting/fundamentals" target="_blank" rel="noopener noreferrer">evidence</a>

    — documents, files, or URLs that support the reported values.
  </Step>
</Steps>

<Warning>
  A broken audit trail is a verification failure. If a verifier asks "where did this 29.36 tCO2e come from?" and you can't trace it back to a delivery ticket and weighbridge slip, the batch won't pass verification.
</Warning>

## Principle 4: Don't Repeat Yourself

<Tabs>
  <Tab title="Duplication (avoid)">
    The same emission factor (0.417 kg CO2e/kWh) hardcoded as a constant in three different models. When the grid factor updates, you need to find and change all three.
  </Tab>

  <Tab title="Reuse (prefer)">
    The emission factor stored as a <a href="/production-accounting/data-inputs" target="_blank" rel="noopener noreferrer">static input</a>

    in the resource library. All models reference the same value. Update once, applies everywhere.
  </Tab>
</Tabs>

**Other reuse patterns:**

* Use static inputs for all factors that might change (emission factors, conversion ratios, methodology parameters)
* If multiple batch types need the same calculation, consider whether a single model can serve both
* Keep the number of event types minimal — only add new ones when the data genuinely comes from a different source

***

### Check your understanding

<Accordion icon="circle-question" title="What does 'Least Complexity' mean in model design?">
  Keep models **as simple as the methodology allows**. Every calculation step should correspond to a requirement in the methodology. Don't add unnecessary logic, premature optimization, or "future-proofing." Note: breaking formulas into intermediate steps for clarity is NOT unnecessary complexity — it aids verification. The principle targets unnecessary **logic**, not necessary **steps**.
</Accordion>

<Accordion icon="circle-question" title="Why is 'Explicit Over Implicit' important for verification?">
  Verifiers need to check intermediate values at each step of the calculation. If everything is packed into one complex expression, they can't verify the parts — only the final result. **Explicit intermediate nodes** let verifiers confirm that dry mass is correct, then that carbon content is correct, then that the CO2 conversion is correct, building confidence at each step.
</Accordion>

***

Next, explore advanced techniques for complex projects in [Lesson 6.2: Advanced Techniques](/accounting-academy/module-6/6-2-advanced-techniques).