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.
What you’ll learn in this lesson:
- Optimize model performance for production-scale data volumes
- Create documentation that enables operators to manage the project independently
- Define monitoring requirements and alert conditions
- Complete the production handoff checklist
Performance optimization
Production projects process much more data than test environments. Optimize before going live.Common performance bottlenecks
| Bottleneck | Symptom | Fix |
|---|---|---|
| Too many model nodes | Slow batch generation | Consolidate redundant intermediate nodes |
| Unnecessary aggregations | Model recalculates unchanged values | Review should_aggregate flags — only set where needed |
| Large date ranges | Batch generation times out | Use narrower accounting periods (monthly instead of quarterly) |
| Complex Keisan expressions | Slow per-batch computation | Simplify expressions or break into multiple simpler nodes |
Testing at scale
Before going live, test with a realistic data volume:Estimate production volume
How many events per month? How many batches will be generated? For Mangrove Biochar: ~20 deliveries/month = ~20 batches/month.
Time the batch generation
Run Generate Batches and note how long it takes. If it exceeds 5 minutes, investigate optimization.
Operator documentation
The person who builds the model isn’t always the person who operates it day-to-day. Documentation bridges this gap.What to document
Data Collection Guide
For the team collecting data:
- What events to create and when
- Required datapoints and formats
- How to add events (manual or bulk import)
- Evidence requirements per event type
- Naming conventions for tracking IDs
Operations Guide
For the team running the accounting:
- When to generate batches (cadence, accounting period selection)
- How to resolve validation errors
- Expected output ranges and red flags
- Ledger reconciliation procedures
- How to generate reports
Where to document
Add descriptions directly in Mangrove where possible:- Event type descriptions — explain the purpose and data source
- Datapoint descriptions — specify units, acceptable ranges, and source
- Model node descriptions — explain the calculation and its methodology reference
In-platform documentation is the most durable — it stays with the project and is visible to anyone who opens it. Supplementary documentation (SOPs, runbooks) should reference the in-platform descriptions, not duplicate them.
Monitoring and alerting
Once live, you need to know when something goes wrong before it affects reporting.What to monitor
| Metric | Expected Behavior | Alert When |
|---|---|---|
| Events created per period | Consistent with operations | Significant drop (missing data) or spike (duplicate imports) |
| Batch outputs | Within expected range | Value outside ±20% of historical average |
| Ledger balance | Non-negative, growing | Goes negative or unexpectedly flat |
| Validation errors | Zero | Any persistent validation errors during batch generation |
| Data completeness | All required events present | Missing event types for an accounting period |
Setting up monitoring
Define thresholds
Based on your testing results, define what “normal” looks like for each metric. Use the Module 5 test results as a baseline.
Schedule regular checks
Set a cadence for reviewing the monitoring metrics — weekly or before each batch generation.
Production handoff checklist
Before declaring a project “production-ready,” walk through this final checklist:Configuration
- All event types configured with correct datapoints, slugs, and descriptions
- All static inputs populated with current emission factors and methodology parameters
- Model validated — all nodes produce correct outputs in the Console
- Batch types configured with correct partition cadence and output types
- Ledgers configured with correct units, credit/debit sources, and allocation rules
Testing
- Happy path tests pass — normal data produces correct outputs
- Edge case tests pass — boundary values are handled correctly
- Volume test pass — batch generation completes in reasonable time at production scale
- Ledger reconciliation verified — no negative balances, inputs ≥ outputs
Documentation
- Event type descriptions written in-platform
- Datapoint descriptions include units, ranges, and source
- Model node descriptions reference methodology equations
- Data collection guide created for operators
- Operations guide created for accounting team
Operational readiness
- Monitoring thresholds defined
- Review cadence established
- Escalation path documented
- First live accounting period scheduled
- Operator training completed
Check your understanding
What 4 areas should a production readiness review cover?
What 4 areas should a production readiness review cover?
Configuration (all components properly set up), Testing (happy path, edge cases, volume, and reconciliation), Documentation (in-platform descriptions plus operator guides), and Operational readiness (monitoring, cadences, escalation, training). All four must be complete before going live.
Why is in-platform documentation preferred over external documents?
Why is in-platform documentation preferred over external documents?
In-platform documentation (event type descriptions, datapoint descriptions, model node descriptions) stays with the project and is visible to anyone who opens it. External documents (SOPs, runbooks) can become stale, get lost, or diverge from the actual configuration. In-platform documentation is the most durable and discoverable form.
You’re now ready to finalize your project in the Module 6 Exercise: Prepare for Production Deployment.