Commercial margin: existing implementation reference

The existing report combines invoice-based service contribution, recorded work, private staff-cost estimates and the Xero business accounts. This page retains operational references for interpreting its outputs. Dashboard and render experiments are not requirements for the MSP CRM records and migration exploration.

Sources and access

The browser route is /commercial-margin/dashboard; Power BI uses pbi/commercial-margin/CommercialMargin.pbip. Both consume /commercial-margin/contribution-report with the existing report authentication.

A refresh builds a private snapshot in the background, returning HTTP 202 until ready. Completed snapshots are cached for 15 minutes. A filesystem lock coordinates workers; source failures return an error. COMMERCIAL_MARGIN_CACHE_DIR selects the cache directory, and COMMERCIAL_MARGIN_CONFIG can select a reviewed mapping file instead of config/commercial_margin.json.

config/commercial_services.json controls the July/August CRM capture adapter. The CRM inventory describes the installed service and invoice-line structures. Existing MSP billing continues through its operational Plan, Seat and configured-charge records.

Interpretation and maintenance references

• Current calculation rules: period boundaries, contribution, coverage limits, staff costing and the bridge to actual Xero profit or loss.
• Technical reference: source tables, relationships, filters and DAX measures.
• Private staff-cost configuration: restricted inputs and server configuration.
• Invoice reconciliation process: the separate operator actions that can write CRM records.

Source code remains in app/commercial_margin/, with browser routes in app/blueprints/report_exports.py. This documentation cleanup does not deploy, remove or change those implementations.